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Preface 


Network Interprocess Communication (NetIPC) is a programmatic service provided 
by the HP 9000 Networking product. The NetIPC Programmer’s Guide is the primary 
reference manual for programmers who write or maintain NetIPC applications on HP 
9000 computers. This manual should also be read by Node Managers before 
designing an HP 9000 network, so that they have a clear understanding of the features 
provided by NetIPC. 

This manual is organized as follows: 

Chapter I “NetIPC Concepts,” explains how NetIPC establishes and 

terminates connections between processes to exchange data. This 
chapter also introduces the NetIPC calls that perform these tasks. 

Chapter 2 “Cross-System NetIPC,” describes special programming 

considerations you should be aware of when writing an HP 9000 
NetIPC program that will communicate with a peer NetIPC process 
at an HP 1000 A-Series, HP 3000, or HP 3000 Series 900. 

Chapter 3 “NetIPC Calls,” provides a detailed description of each NetIPC call 

in alphabetical order. This chapter also explains the structure and 
function of several parameters that are common to multiple NetIPC 
calls. 

Appendix A “Sample NetIPC Programs,” presents NetIPC sample programs in C 
and FORTRAN. 

Appendix B “Error Messages,” lists and describes the error messages that can be 
produced by NetIPC. 

Appendix C “System Calls and NetIPC Sockets,” lists and describes the HP-UX 
system calls that operate on NS sockets. 

Appendix D “LAN/9000 Series 600/800 Migration,” compares the NS/9000 

Series 600/800 and HP 9000 Series 600/800 products to the NS/1000 
and NS/9000 products. 

Appendix E “Porting NetIPC Programs,” summarizes the differences and 

provides information to help you port NetIPC programs between an 
HP 1000 and an HP 9000 Series 600/800 computer. 
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Documentation Map 


The following documentation map lists the manuals containing information related to 
the product described in this manual. You may need information from one or all of 
these manuals. 

NS/1000 User I Programmer Reference Manual 

NetIPC 3000fV Programmer’s Reference Manual 

NetIPC 3000/XL Programmer’s Reference Manual 

HP 9000 Using Network Services 

HP-UX Reference Manual 

PORT/HP-UX Migration Analysis Utility Manual 

HP FORTRAN 77/HP-UX Reference Manual 

HP C Reference Manual 

HP C/HP-UX Reference Manual Supplement 

HP Pascal Reference Manual 

FORTRAN 77 Reference Manual 

Pascal/1000 Reference Manual 

HP FORTRAN 77/HP-UX Migration Guide 

HP Pascal/HP-UX Migration Guide 
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NetIPC Concepts 


Note The information contained in this manual applies to both the Series 
300/400 and Series 600/700/800 HP 9000 computer systems. Any 
differences in installation, configuration, or operation are specifically 
noted. 


Network Interprocess Communication (NetIPC) is a service that enables processes on 
the same or different nodes to communicate using a series of programmatic calls. 
Processes that use NetIPC calls gain access to the communication services provided by 
the network protocols utilized by the HP 9000 networking products. NetIPC does not 
encompass a protocol of its own, but acts as a generic interface to these protocols. 

A NetIPC process running on an HP 9000 computer can communicate with a peer 
process at: 

■ Another HP 9000 computer (Series 600/700/800 or 300/400). 

■ An HP 1000 A-Series computer. 

■ An HP 3000 computer (MPE-V or Series 900). 

■ A PC on an HP OfficeShare Network. 

NetIPC communication between processes running on computers of different types 
(between an HP 9000 and an HP 3000, for example) is referred to as cross-system 
NetIPC. 
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Note NetIPC communication between an HP 9000 Series 600/700/800 and HP 
9000 Series 300/400 is not considered cross-system NetIPC because both 
systems are HP 9000s. 

HP 9000 NetIPC for the Series 300/400 and Series 600/700/800 is not 
compatible with Berkeley IPC (also known as “Berkeley Sockets” or 
“BSD IPC”) or the interprocess communication service that is part of the 
NS/9000 Series 500 product. 


The “Cross-System NetIPC” chapter describes special programming considerations 
you should be aware of when writing an HP 9000 NetIPC program that will 
communicate with a peer NetIPC process at a different type of computer system. For 
information about writing a NetIPC program to run on an HP 1000 A-Series, PC, HP 
3000, or HP 3000 Series 900, you must refer to the following manuals: 

■ NS/1000 User/Programmer Reference Manual 

■ NetIPC 3000/VProgrammer’s Reference Manual. 

■ NetIPC 3000/XL Programmer’s Reference Manual 

■ PC NetIPC/RPM Programmer’s Reference Guide. 
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Chapter Overview 

The information presented in this chapter is organized into the following major 

sections: 

■ Sockets. Describes the fundamental building block of interprocess communication, 
the socket. 

■ Connections. Defines key terms used to describe NetIPC connections. 

■ Establishing a VC Connection. Explains how to use NetIPC calls to establish a 
virtual circuit (VC) connection. 

■ Connection Establishment Summary. Describes the sequences of NetIPC calls 
used to establish a virtual circuit connection. 

■ Sending and Receiving Data. Describes the different modes of data exchange 
provided by NetIPC and explains how to use NetIPC calls to send and receive data. 

■ Shutting Down a Connection. Explains how to use NetIPC calls to close a virtual 
circuit connection. 

■ Summary of NetIPC Calls. Presents a brief description of each of the HP 9000 
NetIPC calls. 
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Sockets 

NetIPC processes communicate with each other by means of sockets. A socket is an 
endpoint through which connections can be established, and data can be sent and 
received. Processes communicate through sockets via NetIPC calls. The Transport 
Layer’s Transmission Control Protocol (TCP) regulates the transmission of data to 
and from sockets. Although data must pass through the control of lower-level 
protocols and, if necessary, through intervening nodes, these details are transparent to 
NetIPC processes when they send and receive data. 
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Connections 

Before two processes can communicate, one side (the passive side or the server) must 
create a call socket by calling i pccreate. The process which creates the call socket 
may name the socket by calling i pcname. This allows the other side (the active side 
or client) to obtain address information regarding the server by calling i pci ookup. 
Alternatively, the client may obtain address information regarding the server by calling 
ipcdest. 

The routines i pcname, i pci ookup, and ipcnamerase allow sockets to be referred to 
by ASCII names rather than protocol addresses. When i pcname is called, the ASCII 
name and information identifying the call socket being named are recorded in a table. 
When i pci ookup is called, the nodename is examined first. If the nodename 
parameter specifies the local node, then the name table on that local node is searched 
for the specified socket name. If the nodename refers to a remote node, then 

1. the address of that remote node is determined, 

2. a request is sent to that node, 

3. the name table on that remote is searched, and 

4. the result of that search is returned in a reply message to the local node indicating 
i pci ookup is complete. 

An alternative to i pci ookup is i pcdest which allows you to specify a protocol 
address, also known as a port, rather than a socket name. The network address of the 
node specified by the nodename is obtained and stored along with the protocol 
address, and i pcdest is complete. 

Both i pci ookup and ipcdest return a destination descriptor. A destination 
descriptor is an integer which indexes a data structure just as a file descriptor is an 
integer which indexes a file. A destination descriptor contains address information 
which identifies a node on the network and a call socket at that node. The 
information in a destination descriptor is the same address information passed to the 
BSD IPC networking routine “connect.” 

Once a client process has obtained a destination descriptor, it may initiate a virtual 
circuit connection by calling i pcconnect. A virtual circuit is a connection using a 
reliable transport protocol, in this case TCP, which guarantees that data are not 
corrupted, lost, duplicated, or received out of order. 
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Descriptors 

NetIPC processes acting as clients reference destination descriptors and virtual 
circuit socket descriptors. NetIPC processes acting as servers reference virtual 
circuit socket descriptors and call socket descriptors. A single process can act as both 
a client and a server. 

■ Call Socket Descriptor. A call socket descriptor references a data structure 
created by calling i pccreate which allows server processes to create virtual circuit 
connections. The NetIPC routine i pccreate is equivalent to the BSD networking 
routines “socket,” “bind,” and “listen.” 

■ Destination Descriptor. A destination descriptor references a data structure that 
contains address information about a destination call socket. A destination 
descriptor must be obtained before a process can connect to the destination call 
socket. A process obtains a destination descriptor by invoking i pci ookup () or 
ipcdest(). 

■ VC Socket Descriptor. A VC socket descriptor refers to a VC socket. A VC 
socket is the endpoint of a virtual circuit connection betwen two processes. VC 
socket descriptors are returned by i pcrecvn () and i pcconnect ( ). 

Socket descriptors are allocated from the same space as file descriptors. A process 
may have a maximum of 1024 socket and file descriptors. Therefore, sockets are 
accessible through the standard HP-UX file system calls such as read ( ), wri te(), 
ioctl (), fcntl (), select(), stat(), dup(), writev() and readv(). For more 
information on using these calls with NetIPC sockets, refer to Appendix C of this 
manual. 
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Table 1-1. Descriptor Type and Definitions 


Descriptor 

Type 

Parameter 

Name 

Description 

Returned as 

Output From 

call socket 
descriptor 

calldesc 

Refers to a call socket. 

A call socket is used by 
server processes to build 
a VC socket. 

ipccreate() 

destination 

descriptor 

destdesc 

Refers to descriptor 
referencing address 
information used to 
direct requests to a 
certain call socket at a 
certain node. 

ipc1ookup() 

ipcdest() 

VC socket 
descriptor 

vcdesc 

Refers to a VC socket. 

A VC socket is the 
endpoint of a virtual 
circuit connection 
between two processes. 

i pcconnect() 
i pcrecvcn() 


Socket Ownership 

When a NetIPC process creates a call socket by calling i pccreate( ), or 
creates a VC socket by calling i pcconnect () or i pcrecvcn (), it is said to 
own the socket. 

A process can also become an owner of a socket by inheriting a socket 
descriptor. NetIPC descriptors (call socket, VC socket, and destination), like 
file descriptors, are copied to the child process when a process forks. As a 
result, more than one process can have a descriptor for the same socket. Any 
process that has a descriptor is considered to be an owner of that descriptor. 
As a programmer, you are responsible for regulating the use of shared 
descriptors. 

A process may have access to a maximum of 1024 descriptors at one time. 

This limit includes file descriptors as well as socket descriptors. 
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Establishing a VC Connection 

Establishing a connection between two processes requires that one process create a 
call socket which the other process can connect to. The process which creates the call 
socket is often referred to as the passive side or the server. The process which 
initiates the connection is often referred to as the active side or client. The typical 
use of the client-server model involves a server process which creates a call socket, 
receives a connection, and forks a child to handle that connection while the server 
listens for another connection. 

As a programmer, you are responsible for synchronizing your NetIPC programs so 
that the NetIPC calls are executed in the manner illustrated by the following drawings 
and text. 

Although only two processes are shown in this example, this is not meant to imply 
that communication cannot exist between more than two processes. Either or both of 
the processes shown can establish virtual circuit connections with other processes. 
Secondary or auxiliary connections can also be set up between the same two processes. 

NetIPC does not provide a call to schedule a remote process. Remote HP 9000 
processes must be manually started or can be scheduled by user-written daemons. 

You can start the daemon at system start up by invoking the daemon from the 
/etc/netlinkrc file. 

For information about scheduling remote programs on other HP computers, refer to 
the “Cross-System NetIPC” chapter. 
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1. Creating a Call Socket 

Before communication can begin, the server process must create a call socket by 
calling ipccreate. The ipccreate routine creates a call socket and returns a call 
socket descriptor in its ca 7 Idesc parameter. The call socket descriptor is used in 
subsequent NetIPC calls. 


Server 



Figure 1 -1. ipccreateQ (Server) 
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2. Naming a Call Socket 

After the server creates the socket, it may optionally name that socket. Naming the 
socket allows client processes to make a connection if they know the socket name, but 
not the protocol specific address. Alternatively, the server could create a call socket 
at a specific protocol address. In that case the client process would need to know the 
protocol address instead of the socket name. Socket names are considered an 
advantage over protocol addresses because when a server names a socket, that socket 
is guaranteed to get a unique protocol address. Several users or programs can 
operate using named sockets without danger of accidentally using a common protocol 
address. 

The server process names a call socket by calling i pcname. The socket name is then 
recorded in the local socket registry name table. Remember that the server process 
must name the socket before the client process calls i pci ookup. 


Server 
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3. Finding A Call Socket Name 

The client process must get address information regarding the server process by 
calling either i pci ookup or i pcdest. If the server process named the call socket, 
then the client process must call i pci ookup. If the server process created the call 
socket at a specific protocol address, then the client process must call i pcdest. 

Both i pci ookup and i pcdest return a destination descriptor to the user. The 
destination descriptor identifies a data structure which contains address information 
about the server’s call socket. 

It may be difficult to ensure that a socket name is placed in the socket registry prior 
to being “looked up” by another process. Several ways to avoid this timing problem 
are outlined in the discussion of i pci ookup () in the “NetIPC Calls” chapter. 


Client Server 



Figure 1 -3. ipcIookupQ (Client) 
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4. Requesting a Connection 

The client process specifies the destination descriptor returned by i pci ookup or 
i pcdest when it calls i pcconnect. The routine i pcconnect will create a virtual 
circuit socket and initiate, but not complete, a connect. The virtual circuit socket (vc 
socket) is returned to the user in the vcdesc parameter. The vc socket may not be 
used to send or receive data until the connection has been completed. The client 
process must call i pcrecv to determine when the connection is complete. 


Client 


Server 



Figure 1-4. ipcconnectQ (Client) 
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5. Receiving a Connection 

The server process receives a connection by calling i pcrecvcn. The routine 
i pcrecvcn references the call socket descriptor and returns a virtual circuit socket 
descriptor to the user. The vc socket descriptor can be used to send and receive data. 
Note that the connection is automatically accepted on the server’s behalf when the 
connection is initially requested by the client process. The client process can 
determine that the connection is “established” before the server calls i pcrecvcn. 
Any data which the client sends before the server calls ipcrecvcnis queued. If the 
client expects data from the server, it may timeout waiting for data even though the 
server has not done an i pcrecvcn. After the server calls i pcrecvcn, it can call 
i pcrecv to read data sent by the client. 


Client Server 



Figure 1-5. ipcrecvcnQ (Server) 
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6. Checking the Status of a Connection 

After the client calls i pcconnect, it must call i pcrecv to determine when the 
connection is completed. 


Client Server 



Figure 1-6. ipcrecvQ (Client) 


Note When the client considers the connection established, it may be different 
from when the server considers the connection established as described 
above. Once the connection is established, data transfer can begin using 
the vc socket descriptors and the i pc send and i pcrecv commands. 

Refer to the “NetIPC Calls” chapter for a detailed description of i pc send 
and i pcrecv. 
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Connection Establishment Summary 

Figures 1-7 and 1-8 illustrate the two alternate sequences of NetIPC calls that are 
used to establish a virtual circuit connection. Figure 1-7 summarizes the information 
presented in Figures 1-2 through 1-6. 

Client Server 



1. "Look up’ name 1. Create call socket 

2. Request connection 2. Name call socket 

3. Check status of 3. Receive connection 

connection request 

Figure 1-7. Establishing Connection with ipclookup Call 
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Figure 1-8 summarizes a different way to establish a virtual circuit connection using 

ipcdest. 


Client Server 


ipcdestO 

ipcconnectO 

ipcrecvO 


1. ipcdest to well-known 
address 

2. Request connection 

3. Check status of 
connection 


ipccreateO 

ipcrecvcnO 


1. Create call socket with 
well-known address 

2. Receive connection 
request 


Figure 1-8. Establishing Connection with ipcdest Call 

In both figures on the client side (that is, at the client’s node), steps 2 and 3 are the 
same, i pci ookup and i pcname reference a destination call socket by name whereas 
ipcdest references the destination call socket by its well-known address. Note that 
the advantage of using i pci ookup is that names might be easier to remember and 
use. With i pedest, the address must be unique and other processes must cooperate 
and not use that same address. 
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Sending and Receiving Data 

Once a virtual circuit connection is established, processes can send and receive data 
using the NetIPC calls i pcsend () and i pcrecv (). i pcsend () is used to send data 
on an established connection, i pcrecv( ) is used to receive data on an established 
connection. (Note that i pcrecv( ) has a dual function: to establish a virtual circuit 
connection and to receive data on a previously established connection.) 


Stream Mode 

All data transfers between NetIPC processes are in stream mode. Stream mode 
adheres to the Transport Layer’s Transmission Control Protocol (TCP). In stream 
mode, data is transmitted in a stream of bytes; there are no end-of-message markers. 
This means that the data received by an individual i pcrecv () request may not be 
equivalent to a message sent by an individual i pcsend () call. In fact, the data 
received may contain part of a message or multiple messages sent by multiple 
i pcsend () calls. Although no attempt is made to preserve boundaries between data 
sent at different times, the data received will always be in the correct order (in the 
order that the messages were sent). 

You may specify the maximum number of bytes that you are willing to receive through 
a parameter of the i pcrecv () call. When the call completes, this parameter will 
contain the number of bytes actually received. The amount of data received will 
never be more than the amount that was requested, but it may be less. Whether or 
not an i pcrecv () call will receive less data than it requested is determined by the 
NSF_DATA_WAIT bit of the f 7 ags parameter. If the NSF_DATA_WAIT bit is set, 
i pcrecv () will never receive less than the requested amount; if the NSFDATAWAIT 
bit is not set, i pcrecv () may receive less data than was requested. 
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Caution The NetIPC NSF_DATA_WAIT flag can cause a program to block for an 
extreme period of time (for example, eight minutes for 8 bytes). It is 
recommended that NetIPC programs not use NSF_DATA_WAIT but 
loop until ail data is received instead. Refer to the “Receiving Data” 
section of the “NetIPC Calls” chapter for the specific loop information. 


If an i pcrecv () call requests more data than is queued on a VC socket, one of the 
following situations will result: 

■ If the VC socket is in synchronous mode, the calling process will suspend until 
enough data is queued to satisfy the i pcrecv () request. If enough data does not 
arrive within the synchronous time-out period to satisfy the request, a “time out” 
error (error code 59) will be returned. 

■ If the VC socket is in asynchronous mode, a “would block” error (error code 56) 
will be returned. 

For more information on receiving data, refer to the discussion of i pcrecv () in the 
“NetIPC Calls” chapter. 


Interpreting Data Received 

As stated in the previous discussion of stream modes, the data received by an 
i pcrecv () call may contain part of a message or multiple messages sent by multiple 
i pcsend () calls. In addition, if the NSF_DATA_WAIT bit of the flags parameter is not 
set, the receiving process may receive less data than it requested. 

If an application does not need to receive data in the form of individual messages, it 
can simply process the data on the receiving side. However, if an application is 
concerned about messages, the programmer must devise a scheme to allow the 
receiving side to determine what the messages are and whether all of the expected 
messages have been received. 

If the messages are of a known length , the receiving process can execute a loop which 
calls i pcrecv () with a maximum number of bytes equal to the length of the portion 
of the message not yet received. Since i pcrecv () returns the actual number of bytes 
received in its dlen parameter, the loop can continue to execute until all of the bytes 
of the message have been received as indicated by this parameter. 
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If the length of the messages are not known, the sending side may send the length of 
the message as the first part of each message. In this scenario, the receiving side must 
execute two i pcrecv( ) loops for each message: the first to receive the length; the 
second to receive the data. 


Synchronous and Asynchronous Socket Modes 

When a send operation is performed on a socket, data is moved out of process space 
into an outbound transmission buffer. Similarly, when a receive operation is 
performed on a socket, data is moved from an inbound transmission buffer into 
process space. Sometimes a send or receive request cannot be immediately satisfied. 
In the case of i pcsend (), an empty transmission buffer may not be available; an 
i pcrecv () request may not be satisfiable because data-filled transmission buffers are 
not queued on the referenced socket. When either of these situations occur, NetIPC 
must decide whether to fail the request or suspend the process until the request can 
be satisfied. This decision is based upon whether the socket being manipulated is in 
synchronous or asynchronous mode. 

Sockets are automatically placed in synchronous mode when they are created. When 
a socket is in synchronous mode, send and receive requests that reference it cause the 
the calling process to be suspended if the requests cannot be immediately satisfied. A 
process that has been suspended will remain suspended until the request is satisfied, a 
synchronous time-out occurs, a signal arrives, or an error is detected. Each 
synchronous socket has a timer associated with it that can be modified with an 
i pccontrol () call. This timer determines how long a NetIPC call will block on the 
socket while waiting for its request to be satisfied. A NetIPC call will not block 
forever unless the synchronous time-out value is set to zero with an i pccontrol () 
call. 

Three NetIPC calls, ipcsend(), ipcrecv() and ipcrecvcn(), support 
asynchronous as well as synchronous I/O. (The i pcconnect () call is by definition an 
asynchronous call; the remaining NetIPC calls do not support asynchronous I/O.) 
Sockets can be placed in asynchronous mode by calling i pccontrol () and specifying 
NSCNBIOENABLE (code 1) in the request parameter. Send and receive requests 
directed against a socket in this mode do not cause the calling process to be 
suspended if the requests cannot be immediately satisfied. Instead, an 
NSR WOULD BLOCK (code 56) error is returned and the process is free to perform 
other tasks before retrying the request. 

Refer to the discussion of i pcrecvcn () in the “NetIPC Calls” chapter for 
information about how this call functions in synchronous and asynchronous mode. 
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Altering the Synchronous Time-out 

If the NetIPC calls ipcsend(), ipcrecv(), and ipcrecvcn() are used 
synchronously, it may be necessary to alter the synchronous time-out value by calling 
ipccontrol (). The default synchronous time-out is 60 seconds. The synchronous 
time-out determines: 

■ How long i pc s end () will suspend the calling program if it cannot immediately 
obtain the buffer space needed to accommodate its data or if the process on the 
receiving end cannot receive the data being sent to it. 

■ How long i pcrecv () will suspend the calling program if its request for data cannot 
be satisfied or if a “successful” connection status cannot be obtained. 

■ How long i pcrecvcn () will suspend the calling program while waiting for a 
connection request. 

For information on changing the synchronous time-out for specific calls, refer to the 
call descriptions in the “NetIPC Calls” chapter. 


Read and Write Thresholds 

For efficiency, a process using asynchronous sockets must be able to determine 
whether a VC socket can satisfy an i pcsend () or i pcrecv () call before the request 
is issued. The i pcselect( ) cal 1 addresses this problem by providing socket 
status information. Included in this information is whether or not: 

■ A VC socket is readable. 

■ A VC socket is writable. 

The i pcsel ect () call determines whether or not a VC socket is readable by 
examining the socket’s read threshold. A VC socket is considered readable if it can 
immediately satisfy an i pcrecv ( ) request for a number of bytes greater than or 
equal to its read threshold. The read threshold is used by i pcsel ect () to check if 
there are at least that many bytes in the system ready for reading. 
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Similarly, i pcsel ect () determines whether or not a VC socket is writable by 
examining the socket’s write threshold. A VC socket is considered writable if it can 
immediately satisfy an i pc send () request for a number of bytes greater than or 
equal to its write threshold. The write threshold is used by i pcsel ect () to check if 
there are at least that many bytes in the system to be used as a buffer space for 
writing. If i pcsel ect indicates that a socket is writable, the subsequent write may 
still fail due to lack of memory available. System memory may be consumed between 
the i pcsel ect and the subsequent ipcsend. 

The i pcsel ect () call will not return accurate status information unless a socket’s 
read and write thresholds are set to the correct number of bytes. (These thresholds 
are initially set to one byte. You can alter this value by calling i pccontrol (). Refer 
to the discussion of this call for more information.) The number of bytes that you 
expect to send or receive on a socket should determine the correct read and write 
threshold settings. As a general rule, you should set a socket’s read threshold to the 
same number of bytes as the length of the data you expect to receive on that socket 
Similarly, you should set a socket’s write threshold to the same number of bytes you 
expect to send on that socket. Consider the following example: Process B will always 
issue i pcsend () calls with 64 bytes of data on VC socket X. Therefore, socket X’s 
write threshold should also be 64 bytes. Similarly, if Process B expects to issue 
64-byte i pcrecv () requests on socket X, socket X’s read threshold should be set to 
64 bytes as well. 

If you expect to receive variable length data on a particular VC socket, the socket’s 
read threshold should be set to the length of the shortest amount of data you expect 
to receive. If you expect to send variable length data on a particular VC socket, the 
socket’s write threshold should be set to the length of the longest amount of data you 
expect to send. 


Note The read and write thresholds are used exclusively by the i pcsel ect () 
call. They have no effect on other NetIPC calls. 


For more information about using sockets in asynchronous mode, refer to the 
discussions of i pcsel ect (), ipccontrol (), i pcsend (), i pcrecv (), and 
ipcrecvcn(). 
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Signals 

Signals will interrupt NetIPC calls that would otherwise suspend. NetIPC calls that 
are interrupted by signals are not restartable. 

NetIPC calls behave the same way as intemiptable HP-UX system calls with the 
following exception: When a NetIPC call is interrupted by a signal and the 
sc_syscall_action field is set to SIG_RETURN, the following occurs: 

1. the NetIPC call aborts, 

2. the interrupted call’s result parameter is set to NSR_SIGNAL_INDICATION, and 

3. the interrupted program continues past the previously blocked NetIPC call. 

When an HP-UX system call is interrupted, the errno variable is set to EINTR. This 
does not occur when the call is a NetIPC call. Instead, the interrupted call’s result 
parameter is set to NSR_SIGNAL_INDICATION. 

NetIPC has also defined values to be returned to the sc_syscall field. These values 
are defined in the HP-UX include file /usr/i ncl ude/sys/syscal 1. h. 

For more information on signals, refer to signal (2) and sigvector(2) described in 
the HP-UX Reference Manual. 
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Shutting Down a Connection 

Processes should close virtual circuit connections they no longer need by calling 
i pcshutdown () to release the VC socket descriptor that references the connection. 


Note The i pcshutdown () call can also be used to release call socket 
descriptors and destination descriptors. Refer to the discussion of 
i pcshutdown () in the “NetIPC Calls” chapter for more information on 
releasing these types of descriptors. 


Because i pcshutdown () takes effect very quickly, any data that is in transit on the 
connection, including any data that has already been queued on the destination VC 
socket, may be destroyed before its intended recipient is able to receive it. To ensure 
that no data is lost during connection shutdown, specify the 
NSFGRACEFULRELEASE flag. 

When a NetIPC process releases a VC socket descriptor that is shared by other 
processes (i.e., other processes have copies of that descriptor), the descriptors owned 
by the other processes are not affected. The i pcshutdown () call does not operate 
on the VC socket referenced by a VC socket descriptor unless the descriptor is the 
only descriptor for that socket. A VC socket is destroyed along with its VC socket 
descriptor only when the descriptor being released is the sole descriptor for that socket. 
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Summary of NetIPC Calls 

The following is a summary of all the HP 9000 NetIPC calls. 

Call Description 

i pcconnect () Requests a virtual circuit to another program and returns a 

VC socket descriptor which identifies a VC socket endpoint 
at the calling program. 

i pccontrol () Performs special operations on sockets such as enabling 

synchronous and asynchronous mode, changing the 
synchronous timeouts, and setting read and write thresholds. 

i pccreate() Creates a call socket for the calling program. 

i pedest () Returns a destination descriptor that the calling process can 

use to establish a connection to another process. 

i pcerrmsg () Returns an error message for a particular NetIPC error 

number. 

i pcerrstr () Provides text describing NetIPC error numbers. 

i pegetnodename () Returns the NetIPC node name belonging to the local host. 

i pci ookup () Searches the socket registry for a socket name and returns a 

destination descriptor that the calling process can use to 
establish a connection to another process. 

i pename () Associates a name with a call socket descriptor or 

destination descriptor and stores it in the socket registry. 

i penamerase () Removes a name associated with a call socket descriptor or 

destination descriptor from the socket registry. 

i pereev () Checks the status of a connection or receives data on a 

previously established connection. 
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ipcrecvcn() 


ipcselect() 


ipcsend() 

ipcsetnodename() 

ipcshutdown() 


Receives a connection request from another program and 
returns a VC socket descriptor that describes a VC socket 
endpoint at the calling program. 

Enables a program to detect and/or wait for the occurrence 
of any of several events across multiple call or VC sockets. 

Note that if i pcs el ect indicates that a socket is writable, 
the subsequent write may still fail due to lack of memory 
available. System memory may be consumed between the 
i pcsel ect and the subsequent i pcsend. 

Sends data to another program on a virtual circuit. 

Defines the NetIPC node name for the local host. 

Releases a descriptor. Also releases the socket referenced 
by the descriptor if the descriptor is the only descriptor that 
references that socket. 
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Cross-System NetIPC 


NetIPC communication between processes running on computers of different types is 
referred to as cross-system NetIPC. This chapter describes the special programming 
considerations that you should be aware of when writing an HP 9000 NetIPC program 
that will communicate with a peer NetIPC process at an HP 1000 A-Series computer, 
an HP 3000 (MPE-V or Series 900) computer, or a PC. 

NetIPC communication between an HP 9000 Series 600/700/800 and HP 9000 Series 
300/400 is not considered cross-system NetIPC because both systems are HP 9000s. 
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Chapter Overview 

Before reading this chapter, you must have a good understanding of the NetIPC 
concepts and calls. Read the “NetIPC Concepts” chapter and review the “NetIPC 
Calls” chapter before proceeding. 

This chapter does not explain how to write a NetIPC program to run on an HP 1000 
A-Series, PC, HP 3000 or HP 3000 Series 900 computer. For this information, refer 
to the following manuals: 

■ NS/1000 User/Programmer Reference Manual. 

■ NetIPC3000/VProgrammer’s Reference Manual 

■ NetIPC3000/XL Programmer’s Reference Manual 

■ PC NetIPC/RPM Programmer’s Reference Guide. 

The remainder of the material presented in this chapter is organized into the 
following major sections: 

■ Software Revision Codes. Lists the software revision codes associated with the 
NetIPC software that provides the cross-system functionality described in this 
chapter. 

■ Local and Remote NetIPC Calls. Divides NetIPC calls into two categories, local 
and remote, and describes how these calls are used in cross-system programs. 

■ HP 9000 to HP 1000 NetIPC. Describes differences between the HP 9000 and HP 
1000 NetIPC implementations. 

■ HP 9000 to HP 3000 NetIPC. Describes differences between the HP 9000 and HP 
3000 NetIPC implementations. 

■ HP 9000 to PC NetIPC. Describes differences between the HP 9000 and PC 
NetIPC implementations. 

■ Process Scheduling. Describes how to schedule a peer NetIPC process at an HP 
9000, HP 3000 and HP 1000 system. 
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Software Revision Codes 

In order for cross-system NetIPC to function properly, the HP 9000, HP 1000 and HP 
3000 NetIPC software revision codes must be as follows: 

■ LAN/9000 Series 600/800 software revision code 1.1 or later for Series 600/800 to 
HP 1000 A-Series NetIPC 

■ LAN/9000 Series 600/800 software revision code 2.1 or later for Series 600/800 to 
HP 3000 NetIPC 

■ NS-ARPA Services software revision code 6.2 or later for the Series 300/400. 

■ NS/1000 software revision code 5.0 or later for the HP 1000 A-Series. 

■ ThinLAN 3000/V Link revision code V-Delta-1 MIT or later (used with IEEE 
802.3 LAN only) for the HP 3000 MPE-V. 

■ ThinLAN 3000/XL Link revision code 1.2 or greater for the HP 3000 Series 900. 

■ PC revision B.00.01. 
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Local and Remote NetIPC Calls 

NetIPC calls can be separated into two categories: local and remote. 


Local NetIPC Calls 

Local NetIPC calls are used to set up or prepare the local node for interprocess 
communication with the remote node. Tlie resulting impact of the local call is only to 
the local node; no information is passed to the remote node. 

Because local NetIPC calls do not affect the peer process, there are no cross-system 
programming considerations associated with these calls. Table 2-1 lists the HP 1000, 
HP 9000, HP 3000 and PC NetIPC calls that only affect the local process. (An 
asterisk indicates that a particular call is not implemented.) 
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Table 2-1. NetIPC Calls Affecting the Local Process 



— 


PC 

Addopt 

addopt() 

ADDOPT 

AddOpt 

Adrof 

* 

* 

* 

InitOpt 

initopt() 

INITOPT 

InitOpt 

* 

* 

IPCCHECK 

* 

IPCControl 

ipccontrol() 

IPCCONTROL 

IPCControl 

IPCCreate 

ipccreate() 

IPCCREATE 

IPCCreate 

* 

ipcerrmsg() 

IPCERRMSG 

* 

* 

ipcerrstr() 

* 

* 

* 

ipcgetnodename() 

* 

* 

IPCGet 

* 

IPCGET 

* 

IPCGive 

* 

IPCGIVE 

* 

IPCName 

ipcname() 

IPCNAME 

* 

IPCNamerase 

ipcnamerase() 

IPCNAMERASE 

* 

IPCSelect 

ipcselect() 

* 

* 

* 

ipcsetnodename() 

* 

* 

* 

optoverhead() 

0PT0VERHEAD 

OptOverhead 

Readopt 

readopt() 

READ0PT 

ReadOpt 



(NetIPC 3000/V 




only) 


* 

* 

* 

ConvertNetworkLong 

* 

* 

* 

ConvertNetworkShort 

* 

* 

* 

IPCWait 


Although the calls listed in Table 2-1 do not affect cross-system 
communication, keep in mind that you may need to design NetIPC programs 
for different system types differently. This is because NetIPC calls, even those 
with the same name, differ from system type to system type. The following are 
some local call differences to be aware of: 

■ Maximum number of sockets. The maximum number of socket descriptors 
owned by an HP 9000 process at any given time is 2048 (including file 
descriptors); the HP 1000 maximum is 32; the HP 3000 maximum is 64; the 
PC maximum is 21. This number includes call socket, virtual circuit socket, 
and open file descriptors. 
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■ ipccontroK) parameters. The i pccontrol () call supports a different set of 
request codes on different system types. Refer to the NetIPC documentation for a 
particular system (this manual for the HP 9000) for a full description of the request 
codes available on that system. 

■ Destination descriptors. On the HP 1000, destination descriptors are called path 
report descriptors. Both types of descriptors are used in the same way. They 
contain addressing information that is used by a NetIPC process to direct requests 
to a certain call socket at a certain node. 

■ Manipulation of descriptors. The HP 9000 and HP 1000 implementations of 
NetIPC allow you to manipulate call socket and destination descriptors with the 

i pcname () and i pcnamerase () calls; the HP 3000 only allows you to manipulate 
call sockets with these calls. When you use the IPCGive and IPCGet calls on the 
HP1000, you can manipulate call socket and destination descriptors; the HP 3000 
only allows you to manipulate call and VC sockets with these calls. 

■ Asynchronous I/O. The HP 9000 and HP 1000 NetIPC implementations utilize the 
NetIPC i pcsel ect () call to perform asynchronous I/O; the HP 3000 NetIPC 
implementation utilizes the MPE intrinsics IOWA IT and I0D0NTWAIT. PC NetIPC 
usesIPCWait. 

■ Call sockets. On the PC, call sockets are called source sockets and call socket 
descriptors are called source socket descriptors. Both sets of terms are used in the 
same way. 


Note There are many additional differences between local NetIPC calls for the 

HP 9000, HP 1000, HP 3000, and PC. Refer to the NetIPC 
documentation for each system for more information. 
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Remote NetIPC Calls 


Unlike local NetIPC calls, remote NetIPC calls affect the peer process at the remote 
node. Because remote NetIPC calls affect the peer process, there may be 
cross-system programming considerations associated with these calls. 

Table 2-2 lists the HP 9000, HP 1000, HP 3000, and PC NetIPC calls that affect the 
remote process. 


Table 2-2. NetIPC Calls Affecting the Remote Process 



HP 9000 

HP 3000 

PC 

IPCConnect 

ipcconnect() 

IPCCONNECT 

IPCConnect 

IPCDest 

ipcdest() 

IPCDEST 

IPCDest 

IPCLookUP 

ipclookup() 

IPCLOOKUP 

not implemented 

IPCRecv 

ipcrecv() 

IPCRECV 

IPCRecv 

IPCRecvCn 

ipcrecvcn() 

IPCRECVCN 

IPCRecvCn 

IPCSend 

ipcsend() 

IPCSEND 

IPCSend 

IPCShutDown 

ipcshutdown() 

IPCSHUTDOWN 

IPCShutdown 


The remainder of this chapter describes cross-system programming 
considerations for the remote NetIPC calls as they relate to the following 
cross-system pairs: 

■ HP 9000 to HP 1000 A-Series communication. 

■ HP 9000 to HP 3000 (MPE-V and Series 900) communication. 

■ HP 9000 to PC communication. 
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HP 9000 to HP 1000 NetIPC 

When writing an HP 9000 NetIPC program that will communicate with an HP 1000 
NetIPC peer process, you must be aware of certain differences in the HP 9000 and 
HP 1000 NetIPC implementations. These differences, and the NetIPC calls that are 
affected, are listed in Table 2-3. 

Table 2-3. Calls That Affect HP 9000 to HP 1000 NetIPC 


NetIPC Call 

Cross-System Considerations 

ipcconnect() 

Checksumming - When an ipcconnect() call is 
executed on an HP 9000 node, then TCP 
checksumming is always enabled for the HP 
9000-to-HP 1000 connection. 

Send and Receive sizes - The HP 1000 send and 
receive size range is 1 to 8,000 bytes. The HP 9000 
send and receive size range is 1 to 32,767 bytes. 
Although the ranges are different, cross-system 
communication is not affected. Just be sure to 
specify a buffer size within the correct range for the 
respective system. 

ipcdest() 

TCP Protocol Address - The HP 1000 and HP 9000 
implementations of i pccreate () support different 
ranges of permitted TCP protocol addresses that can 
be specified in the opt parameter. However, both 
implementations recommend that users specify TCP 
addresses in the range of 30767 to 32767 decimal for 
cross-system use. The i pcdest () call uses the TCP 
protocol address specified in i pccreate () on the 
remote process. 

ipclookup() 

No differences that affect cross-system operations. 
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Table 2-3. Calls That Affect HP 9000 to HP 1000 NetlPC-con’t 


NetIPC Call Cross-System Considerations 

i pcrecv () Receive size - The HP 1000 receive size range is 1 to 

8,000 bytes. The HP 9000 receive size range is 1 to 
32,767 bytes. Although the range sizes that can be 
specified in the dlen parameter are different, 
cross-system communication is not affected. Just be 
sure to specify a buffer size within the correct range 
for the respective system. 

i pcrecvcn () Checksumming - TCP checksumming is always 

enabled for the HP 9000-to-HP 1000 connection. 

Send and Receive sizes - The HP 1000 send and 
receive size range is 1 to 8,000 bytes. The HP 9000 
send and receive size range is 1 to 32,767 bytes. 
Although the ranges are different, cross-system 
communication is not affected. Just be sure to 
specify a buffer size within the correct range for the 
respective system. 

i pc send () Send size - The HP 1000 send size range is 1 to 

8,000 bytes. The HP 9000 send size range is 1 to 
32,767 bytes. Although the range sizes that can be 
specified in the dlen parameter are different, 
cross-system communication is not affected. Just be 
sure to specify a buffer size within the correct range 
for the respective system. 
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Table 2-3. Calls That Affect HP 9000 to HP 3000 NetIPC-con’t 


NetIPC Call 

Cross-System Considerations 

ipcshutdown() 

Socket Shut Down - The shutdown procedure for 
both HP 1000 and HP 9000 processes is the same, 
except that a “graceful release” flag is provided on 
the HP 9000. If the graceful release flag (flags bit 
17) is set on the HP 9000, the HP 1000 will respond 
as though it were a normal shutdown. The HP 9000 
also supports “shared sockets”; the HP 1000 does 
not. 

Shared sockets are destroyed only when the 
descriptor being released is the sole descriptor for 
that socket. Therefore, the HP 9000 process may 
take longer to close the connection than expected. 


Note There are many additional differences between remote NetIPC 
calls for the HP 9000 and HP 1000 systems. However, these 
differences should not affect the cross-system communication 
capabilities of your program because they affect the local node 
only. Refer to Appendix E, “Porting NetIPC Programs,” for a 
summary of the differences between the HP 9000 and HP 1000 
NetIPC implementations. 


NetIPC Error Codes 

NetIPC calls with the same names on HP 9000 and HP 1000 systems may 
return different error codes. Refer to the system’s corresponding NetIPC 
documentation for a complete list of the error codes that are applicable to 
that NetIPC implementation. 
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HP 9000 to HP 3000 NetIPC 

When writing an HP 9000 NetIPC program that will communicate with an HP 3000 
(MPE-V or Series 900) NetIPC peer process, you must be aware of certain 
differences in the HP 9000 and HP 3000 NetIPC implementations. These differences, 
and the NetIPC calls that are affected, are listed in Table 2-4. 


Table 2-4. Calls That Affect HP 9000 to HP 3000 NetIPC 


NetIPC Call 

Cross-System Considerations 

ipcconnect() 

Checksumming - TCP checksumming is always 
enabled for the HP 9000-to-HP 3000 connection. 

Send and Receive sizes - The HP 9000 send and 
receive size range is 1 to 32,767 bytes. The HP 3000 
send and receive size range is 1 to 30,000 bytes. 
Although the ranges are different, cross-system 
communication is not affected. Just be sure to 
specify a buffer size within the correct range for the 
respective system. Note that the default send and 
receive sizes differ on the HP 9000 and the HP 

3000. On the HP 9000, the default send and receive 
size is 100 bytes. On the HP 3000, the default send 
and receive size is less than or equal to 1024 bytes. 
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Table 2-4. Calls That Affect HP 9000 to HP 3000 NetIPC-con’t 


NetIPC Call 

Cross-System Considerations 

ipcdest() 

TCP Protocol Address - The HP 9000 and HP 3000 
implementations of ipccreate() support different 
ranges of permitted TCP protocol addresses that can 
be specified in the opt parameter. However, both 
implementations recommend that users specify TCP 
addresses in the range of 30767 to 32767 decimal for 
cross-system use. The ipcdest() call uses the TCP 
protocol address specified in ipccreate() on the 
remote process. 

ipclookup() 

No differences that affect cross-system operations. 

ipcrecv() 

Receive size - The HP 9000 receive size range is 1 to 
32,767 bytes. The HP 3000 receive size range is 1 to 
30,000 bytes. Although the ranges are different, 
cross-system communication is not affected. Just be 
sure to specify a buffer size within the correct range 
for the respective system. 

ipcrecvcn() 

Checksumming - TCP checksumming is always 
enabled for the HP 9000-to-HP 3000 connection. 


Send and Receive sizes - The HP 9000 send and 
receive size range is 1 to 32,767 bytes. The HP 3000 
send and receive size range is 1 to 30,000 bytes. 
Although the ranges are different, cross-system 
communication is not affected. Just be sure to 
specify a buffer size within the correct range for the 
respective system. Note that the default send and 
receive sizes differ on the HP 9000 and HP 3000. 

On the HP 9000, the default send and receive size is 
100 bytes. On the HP 3000, the default send and 
receive size is less than or equal to 1024 bytes. 
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Table 2-4. Calls That Affect HP 9000 to HP 3000 NetIPC-con’t 


NetIPC Call 

Cross-System Considerations 

ipcsend() 

Send size - The HP 9000 send size range is 1 to 

32,767 bytes. The HP 3000 send size range is 1 to 
30,000 bytes. Although the ranges are different, 
cross-system communication is not affected. Just be 
sure to specify a buffer size within the correct range 
for the respective system. 

Urgent Data - The HP 3000 supports an “urgent 
data” option in the opt parameter. If this bit is set 
by the HP 3000 program, it will be ignored by the 
receiving process on the HP 9000. 

ipcshutdown() 

Socket Shut Down - The shutdown procedure for 

HP 9000 and HP 3000 processes is the same. The 

HP 9000 supports “shared sockets”; the HP 3000 
does not. Shared sockets are not destroyed until 
only one socket descriptor exists (the last socket 
descriptor). Therefore, an HP 9000 process may 
take longer to close the connection than expected. 


Note There are many additional differences between remote NetIPC 
calls for the HP 9000 and HP 3000 systems. However, these 
differences should not affect the cross-system communication 
capabilities of your program because they affect the local node 
only. Refer to the system’s corresponding NetIPC documentation 
to determine all of the differences between NetIPC on the HP 
9000 and HP 3000 systems. 
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NetIPC Error Codes 

NetIPC calls with the same names on HP 9000 and HP 3000 systems may return 
different error codes. Refer to the system’s corresponding NetIPC documentation for 
a complete list of the error codes that are applicable to that NetIPC implementation. 
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HP 9000 to PC NetIPC 

When writing an HP 9000 NetIPC program that will communicate with a PC NetIPC 
peer process, you must be aware of certain differences in the HP 9000 and PC 
NetIPC implementations. These differences, and the NetIPC calls that are affected, 
are listed in Table 2-5. 


Table 2-5. Calls That Affect HP 9000 to PC NetIPC 


NetIPC Call Cross-System Considerations 

IPCConnect Checksumming - With PC NetIPC, the TCP 

checksum option cannot be turned on. On the HP 
9000, the TCP checksum is always on. Therefore, 
the checksum is in effect on both sides of the 
connection. 

Send and Receive sizes - The HP 9000 send and 
receive size range is 1 to 32,767 bytes. The PC send 
and receive size range is 1 to 65,535 bytes. Although 
the ranges are different, cross-system communication 
is not affected. Just be sure to specify a buffer size 
within the correct range for the respective system; 
otherwise, an error will occur. For example, if a PC 
sends a 60,000 byte buffer, the HP 9000 process may 
get all the data by posting two i pcrecv functions of 
30,000 bytes until all the data has been received. 

IPCCreate TCP Protocol Address - The HP 9000 and PC 

IPCDest implementations of IPCCreate support different 

ranges of permitted TCP protocol addresses that can 
be specified in the opt parameter. However, both 
implementations recommend that users specify TCP 
addresses in the range of 30767 to 32767 decimal for 
cross-system use. The IPCDest call uses the TCP 
protocol address specified in IPCCreate on the 
remote process. 
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Table 2-5. Calls That Affect HP 9000 to PC NetIPC-con’t 


NetIPC Call 

Cross-System Considerations 

IPCRecv 

Receive size - The HP 9000 enables you to specify 
the maximum receive size of the data buffer with the 
dlen parameter through an option array. PC NetIPC 
has no option array defined for IPCConnect. This 
does not affect cross-system communication. The 
maximum receive size of the data in the buffer on 
the HP 9000 will determine the receive size buffer 
on the PC. 

IPCRecvCn 

Checksumming - With PC NetIPC, the TCP 
checksum option cannot be turned on. On the HP 
9000, the TCP checksum is always on. Therefore, 
the checksum is in effect on both sides of the 
connection. 

Send and Receive sizes - The HP 9000 send and 
receive size range is 1 to 32,767 bytes. The PC send 
and receive size range is 1 to 65,535 bytes. Although 
the ranges are different, cross-system communication 
is not affected. Just be sure to specify a buffer size 
within the correct range for the respective system. 

IPCSend 

Send size - The HP 9000 enables you to specify the 
maximum send size of the data buffer with the dlen 
parameter through an option array. PC NetIPC has 
no option array defined for IPCConnect. This does 
not affect cross-system communication. The 
maximum send size of the data in the buffer on the 
HP 9000 will determine the send size buffer on the 
PC. 
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Note There are many additional differences between remote NetEPC calls for 
the HP 9000 and PC NetIPC systems. However, these differences should 
not affect the cross-system communication capabilities of your program 
because they affect the local node only. Refer to the system’s 
corresponding NetIPC documentation to determine all of the differences 
between NetIPC on the HP 9000 and PC NetIPC systems. 


NetIPC Error Codes 

NetIPC calls with the same names on HP 9000 and PC NetIPC systems may return 
different error codes. Refer to the system’s corresponding NetIPC documentation for 
a complete list of the error codes that are applicable to that NetIPC implementation. 
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Process Scheduling 

NetIPC does not include a call to schedule a peer process. In programs 
communicating between multiple HP 3000s or multiple HP 1000s, you can use the 
Remote Process Management (RPM) call RPMCREATE to programmatically schedule 
program execution. RPM between HP 9000s and HP 1000s or HP 3000s is not 
currently supported by Hewlett-Packard. 

The following sections describe how to start a process at a remote HP 9000, HP 1000 
and HP 3000 system. 


Remote HP 9000 Process 

Remote HP 9000 processes can be started manually or can be scheduled by daemons. 

To manually start up a NetIPC program, simply logon to the HP 9000 system and run 
the NetIPC program. 

To start a NetIPC process from a daemon, start the daemon at system start up by 
invoking it from the /etc/netl inkrc file. 


Remote HP 1000 Process 

A remote HP 1000 NetIPC process must be ready to execute by being an RTE type 6 
file. HP 1000 processes can be started manually or can be started at system start up. 

To manually start up a NetIPC program, simply logon to the HP 1000 system and run 
the NetIPC program with the RTE XQ (run program without wait) command. 

To have the NetIPC program execute at system start up, put the RTE XQ command in 
the WELCOME file. Refer to the RTE-A User's Manual for a description of the XQ 
command. 
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Remote HP 3000 Process 

HP 3000 processes can be started manually or can be started by a job file. 

To manually start up an HP 3000 NetIPC program, log on to the HP 3000 and run 
the NetIPC program (with the RUN command). 

You can schedule the program to start at a particular time by writing a job file to 
execute the program, and then including time and date parameters in the : STREAM 
command that executes the job file. 


Remote PC NetIPC Process 

To manually start up a PC NetIPC program, enter the NetIPC program name at the 
MS®-DOS prompt. 

To execute from within MS-Windows, copy the NetIPC program files to your windows 
directory and double click with the mouse on the executable file. 
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3 


NetIPC Calls 


This chapter is a reference source for programmers who code applications that utilize 

NetIPC calls. It is assumed that the reader has read and understands the concepts 

presented in the “NetIPC Concepts” chapter. 

The information contained in this chapter is organized as follows: 

■ Programming Languages. Identifies the programming languages in which NetIPC 
programs may be written. 

■ Include Files and Libraries. Describes the NetIPC include file that may be used 
with NetIPC programs written in C and explains how to link and compile NetIPC 
programs written in each of the supported programming languages. 

■ HP 1000 to Series 600/800 Migration. Lists reference sources for programmers 
who will be migrating HP 1000 NetIPC programs to the HP 9000 Series 600/800 
programming environment 

■ NetIPC Common Parameters. Describes parameters that are common to most of 
the NetIPC calls and explains how to use those parameters in each of the supported 
programming languages. 

■ Syntax Conventions. Explains the syntax conventions used on the NetIPC 
reference pages. 

■ NetIPC Reference Pages. Provides reference pages, in alphabetical order, for each 
of the NetIPC calls. 
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Programming Languages 

NetIPC programs may be written in C, Pascal or FORTRAN. For detailed 
information about programming languages, refer to the appropriate language 
reference manual. Programming reference manual titles are listed in the preface of 
this manual. 
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Include Files and Libraries 

A C include file, /usr/i ncl ude/sys/ns_i pc. h, is provided with the NetIPC 
software and should be included in all NetIPC programs that are written in the C 
programming language. This include file contains constant definitions for socket 
types, protocol types, flags parameter bits, ipccontrol () request codes, opt 
parameter option codes, and NetIPC error codes. It also contains the type 
declaration ns_i nt_t that can be used to describe many of the NetIPC call 
parameters. 


Note If you wish to use Pascal or FORTRAN, you must translate the include 

file /usr/i ncl ude/sys/ns_i pc. h into these programming languages. 


A NetIPC library, /usr/1 ib/11 ib-nsipc.ln is also provided with the NetIPC 
software for use with the lint program. For example: 

1 i nt programname -1 nsi pc 

For more information on 1 i nt, refer to the HP-UX Reference Manual. 
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HP 1000 to Series 600/800 Migration 

NetIPC programs written in Pascal and FORTRAN for the HP 1000 environment 
may be transported to HP 9000 Series 600/800 nodes. Refer to the migration manuals 
listed in the preface of this manual for information on migrating HP 1000 Pascal and 
FORTRAN programs to the HP 9000 Series 600/800 environment. 

If you plan to transport HP 1000 NetIPC programs to the Series 600/800, refer to 
Appendix E of this manual for HP 1000 to Series 600/800 NetIPC porting 
information. Refer to Appendix D of this manual for general NS/1000 and 
DS/1000-IV to LAN/9000 Series 600/800 migration information. 
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NetIPC Common Parameters 

The flags , opt , data , result , socketname, and nodename parameters are common 
to many NetIPC calls. 

The opt parameter provides functionality for NetIPC calls and usually has associated 
data. The fl ags parameter enables or disables certain functions for NetIPC calls. 
The result parameter returns error codes for NetIPC calls. The socketname and 
nodename parameters identify sockets and nodes, respectively. 

The following paragraphs provide detailed information regarding the meaning, use 
and structure of each of these parameters. 


Flags Parameter 

The flags parameter is a 32-bit integer that represents various options. By setting 
bits in the fl ags parameter, you can invoke various services in i pcrecv (), 
ipcsend(), ipccontrol () and ipcdest() calls. 

The NetIPC calls ipcconnect(), ipccreate(), ipc1ookup(), ipcrecvcn() and 
ipcshutdown() also include a flags parameter, but in these calls the parameter is 
reserved for future use. The fl ags parameter must be initialized to zero before it is 
used in these calls. The parameter must also be cleared after it is used in these calls if 
it is to be in a subsequent call that requires that the flags parameter be initialized to 
zero. This precaution should be taken because NetIPC calls that do not use the 
flags parameter on input may return non-zero values to the parameter on output. 

The following paragraphs explain how the flags parameter is declared and 
manipulated in the C, Pascal, and FORTRAN programming languages. 
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Note 


NetIPC calls assume that the bits in the flags parameter are numbered 
from left to right with the most significant bit considered to be bit zero and 
the least significant bit considered to be bit 31. 

MSB 

0 1 2 3 4 5 ... 31 Pascal, C, and NetIPC 
MSB 

31 30 29 28 ... 0 FORTRAN 

The remaining examples in this chapter assume the most significant bit is 

0 . 


Using Flags in a C Program 

The C include file /usr/incl ude/sys/ns_ipc. h includes constant definitions that 
should be used when setting bits in the flags parameter. (Refer to the explanations 
of the i pcsend (), i pcrecv () , i pccontrol (), and i pcdest () call descriptions 
later in this chapter for the constants that can be used with these calls.) 

The fl ags parameter should be declared as type ns_i nt_t, which is defined in the C 
include file /usr/i ncl ude/sys/ns_i pc. h. A flags option is set by assigning one of 
the constants defined for the particular call to the flags parameter. In the following 
example, the flags parameter used in an i pcrecv () call is assigned the constant 
NSFPREVIEW. (NSF_PREV IEW sets bit 30 of the fl ags parameter.) 

flags = NSF_PREVIEW; 

In the next example, the NSF PREVIEW and NSF_DATA_WAIT options are selected by 
using the bitwise inclusive OR (|) operator. (NSF_DATA_WAIT sets bit 20 of the 
fl ags parameter.) 

flags = NSF PREVIEW | NSFJ3ATAWAIT; 
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Using Flags in a Pascal Program 

In Pascal, the fl ags parameter may be represented as an array of bits: 

TYPE flags type = packed array [0. .31] of boolean; 

VAR flags : flags_type; 

fl ags [0] refers to the high order bit in the boolean array; f 1 ags [31 ] refers to the 
low order bit. To set a bit in the array, assign the value TRUE to the desired bit. For 
example, 

flags [21] := TRUE; 

would set bit 21 of the flags array. A clear bit would be assigned the value FALSE. 

If you do not want to set any of the bits in the f 1 ags array, but you want to be 
certain that all of the bits are clear, you may make flags type INTEGER and assign it 
the value zero. 


Using Flags in a FORTRAN Program 

In FORTRAN, the flags parameter must be declared as INTEGER*4 (32-bit integer). 
The simplest way to set a bit in this parameter is to use the FORTRAN library 
function i bset (a, b) . The fl ags parameter is passed in the first argument (a) and 
the bit position to be set is passed in the second argument ( b ). 

The i bset function assumes that bits are numbered from right to left, with the most 
significant bit considered to be bit 31 and least significant bit considered to be bit 0. 
NetIPC calls assume that bits are numbered in the opposite direction (i.e., the most 
significant bit is 0, the least significant bit is 31). Therefore, to set the proper bit in 
the flags parameter using i bset, you must subtract the flags value from 31. 

In the following example, bit 21 is set in the flags parameter: 

INTEGERS flags 

C The flags value is subtracted from 31 so that the proper 
C bit is set. This maps ibset's bit numbering convention into 
C NetIPC's. 

flags = ibset(flags,(31-21)) 

Multiple bits can be set by repeating the i bset function. 
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Opt Parameter 

The opt parameter allows you to request optional services when invoking certain 
NetlPC calls. It enables calls that include the opt parameter to accept an arbitrary 
number of arguments that are either protocol or operating system specific. 

Because the opt parameter has a complex structure, NetlPC provides a special set of 
calls that allow you to manipulate the parameter. Table 3-1 summarizes the opt 
parameter calls. Before you can invoke a NetlPC call that includes an opt parameter, 
you must prepare the parameter by using the following opt parameter calls: 

■ First, i n i topt () must be called to initialize the opt parameter. This call allows 
you to specify how many arguments will be placed in the parameter. 

■ Next, addopt () must be called to add an argument and its associated data to the 
opt parameter. (An addopt () call can add only one argument at a time, so you 
must call it multiple times if you want to add multiple arguments to the opt 
parameter.) 

If the opt parameter is not used in a certain call (no options are defined for that call 
or you do not choose to select an option), you must assign a value of zero (0) to the 
opt parameter or pass the constant NSO NULL in its place. 

In addition to ini topt () and addopt (), two optional opt parameter calls are 
provided: readopt () and optoverhead (). The readopt () call allows you to obtain 
option code and argument data associated with a certain opt parameter. The 
optoverhead () call may be used to determine the number of bytes needed for the 
opt parameter, excluding the data area. To determine the length of the entire opt 
parameter, you must add the result of the optoverhead () call to the length of the 
data to be placed in it and then allocate memory for the parameter by calling 
mal 1 oc () . (mal 1 oc () is documented in the HP-UX Reference Manual.) 

The following formula can also be used to determine the opt parameter length before 
coding your application. 

total Jength_of_opt = 4 + 8 * OPTNUMARGUMENTS + DATA; 


3-8 NetlPC Calls 



In this formula, OPTNUMARGUMENTS contains the number of arguments that will be 
placed in the parameter and DATA contains the length in bytes of the data associated 
with all of the arguments. 


Table 3-1. Special NetIPC Calls 


Call 

Description 

addopt() 

Adds an argument and its associated data to an opt 
parameter. 

initopt() 

Initializes an opt parameter so that arguments can be added. 

optoverhead() 

Returns the amount of space needed for the opt parameter 
in bytes, not including the data portion of the parameter. 

readopt() 

Obtains the option code and argument data associated with 
an opt parameter argument. 


A complete description of each opt call, including programmatic examples of the 
initopt() and addopt() calls, is provided in “Special NetIPC Calls” later in this 
chapter. 

The following paragraphs explain how the opt parameter is declared and manipulated 
in the C, Pascal, and FORTRAN programming languages. 


Using Opt in a C Program 

The C include file /usr/i ncl ude/sys/ns i pc. h includes constant definitions that 
should be used when placing options in the opt parameter. (Refer to the 
explanations of the NetIPC calls that utilize the opt parameter for a description of 
the constants that can be used.) 
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The opt parameter should be declared as an array of short (16-bit) integers. For 
example: 

short int opt [optlength]; 

When declared as a array of short integers, the opt parameter can be passed directly 
to the i n i topt () call. For example, 

initopt (opt, optnumarguments, error); 

Alternatively, you can declare the opt parameter as a pointer to a short (16-bit) 
integer. For example: 

short int *opt; 

However, if you use *opt, you must allocate space for the structure before passing it 
toinitopt(). This can be done by using optoverhead() and the malloc() call as 
described in the HP-UX Reference Manual For example: 

datalength = 20; 

optlength = optoverhead (number_entries, error); 
opt = (short*) malloc (datalength + optlength); 


Note The opt data structure must be aligned on a short (16-bit) boundary. 


Using Opt in a Pascal Program 

In Pascal, the opt parameter should be declared as a a packed array of bytes. For 
example: 

TYPE 

byte - 0..255; 

optarray = packed array [0. .optlength] of byte; 

VAR 

opt : optarray; 
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Using Opt in a FORTRAN Program 

In FORTRAN, the opt parameter should be declared as an array of short (16-bit) 
integers. For example: 

SHORT INTEGER opt (opt 7 ength) 


Opt Parameter Structure 


Note The following description is provided for information only. The special 
opt parameter calls are provided to mask this information from the user. 
It is not necessary to understand the opt parameter structure in order to 
use it. 


The following diagrams are provided to illustrate the general form of the opt 
parameter after it has been initialized with the special NetIPC call i n i topt (). In 
Figure 3-1, OPTLENGTH represents the length of the opt parameter from the first byte 
of OPTNUMARGUMENTS to the end of the data segment: 

OPTLENGTH = 8 * OPTNUMARGUMENTS + DATA 

OPTNUMARGUMENTS represents the number of arguments or entries placed in the 
parameter; OPTARGUMENTS is an area containing the arguments themselves; and DATA 
is where the data associated with the arguments is stored. 
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Figure 3-1. Opt Parameter Structure 
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Figure 3-2 illustrates the structure of an opt parameter argument. 0PTI0NC0DE is the 
option code associated with the argument being added; OFFSET is a byte offset into 
the opt record where any data associated with the argument is located; and 
DATALENGTH is the length of the data associated with the argument. This information 
is added to the opt parameter with the special NetIPC call addopt (). (An example 
of adding an argument to the opt parameter is provided in the discussion of 
addopt () later in this chapter.) 



Figure 3-2. OPTARGUMENT Structure 
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Data Parameter 


The data parameters present in ipcsend(), ipcrecv() and ipccontrol () may 
reference data vectors or data buffers. 

Unlike a data buffer, which is a structure containing actual data, a data vector is a 
structure that can describe several data objects. The description of each object 
consists of a byte address and a length. The byte address describes where the object is 
located and the length indicates how much data the object contains. Any kind of data 
object (arrays, portions of arrays, records, simple variables, etc.) can be described by a 
data vector. 

When a data vector is used to identify data to be sent, it describes where the data is 
located. This is referred to as a gathered write. When a data vector is used to 
identify data to be received, it describes where the data is to be placed. This is 
referred to as a scattered read. 

Using data vectors may be more efficient than using data buffers in certain 
circumstances. For example, a process that sends data from several different buffers 
must call i pc send () several times, or copy the data into a packing buffer prior to 
sending it, if its data parameter is a data buffer. However, if its data parameter is a 
data vector, the process may describe all of the buffers in the data parameter and 
transfer it using one i pcsend () call. 


Note Since the data location descriptors contain machine-specific information, 
code using the vectored option may not be portable to other machines. 
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Figure 3-3 is an example of a data vector and the data objects that it represents. The 
data vector describes the characters “HERE IS THE DATA.” 
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Figure 3-3. Vectored Data 


When a data parameter refers to a data vector, the length of the data parameter 
(usually called c/7 e/7) refers to the length of the structure containing the vector. 

For example, if an i pcsend( ) call were to reference the data,vector in Figure 3-3 
above, its dTen parameter would be 24 bytes. (Each byte address and length totals 4 
bytes; each pointer to a data object is also 4 bytes long. There are three sets of byte 
addresses, lengths and pointers. Therefore, 8*3 = 24.) 

Each length in a data vector must be greater than or equal to zero. The format for 
vectors, and the maximum number of vectors that may be specified, are defined in 
/usr/include/sys/uio.h. 
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Result Parameter 


Every NetIPC call has a result parameter. When a NetIPC call encounters an 
error, an error code is returned via this parameter. 


Using Result in a C Program 

Because the result parameter is provided for error return, you should declare 
NetIPC calls to be type void in C programs. In addition, a C include file called 
/usr/i ncl ude/sys/ns i pc. h is provided which contains constant definitions that 
can be used to refer to errors in your C programs. For example, the following C 
program fragment checks for the error NSR_REMOTE_ABORT (code 64) after an 
ipcshutdown() call: 


ipcshutdown(descriptor, &flags, opt, &result); 
i f (resul t == NSR_REMOTE_ABORT) 
goto returnerror; 

The result parameter should be declared as a pointer to type ns_int_t, which is 
defined in the C include file /usr/incl ude/sys/ns_ipc. h. 


Note Passing an invalid or out-of-bounds pointer to the actual resu 11 

argument in a NetIPC call will cause the program to core dump due to a 
memory fault/bus error. A pointer is, in general, considered “bad” if it 
points outside of the user’s memory space. 


Using Result in a Pascal Program 

In Pascal, the result parameter should be declared as type INTEGER. 


Using Result in a FORTRAN Program 

In FORTRAN, the result parameter should be declared as type INTEGER*4. 
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Socket Name Parameter 

The NetIPC calls ipcname(), ipcnamerase(), ipc1ookup() and ipcdest() 
require the use of names to identify either sockets or nodes. A socket name (the 
socketname parameter) may be a maximum of 16 characters long and may consist of 
any ASCII character. Upper and lower case characters are not considered distinct 
(for example, the socket names “john” and “JOHN” are equivalent). 


Node Name Parameter 

A node name (the nodename parameter) refers to a node and has a hierarchical 
structure as follows: 

node [. domain [. organization ]] 

The domain and organizat ion may be useful for grouping nodes and collections of 
nodes, but they currently have no special meaning regarding the structure of the 
network within the LAN product and are optional. They will default to the local 
domain and organization if they are omitted. When all three parts of the node name 
are specified, it is called a fully-qualified node name. 

Each node, domain, and organization name is a maximum of 16 characters long, 
and a period (.) separates each name. The maximum total length of a fully-qualified 
node name is 50 characters. All alphanumeric characters are allowed, including the 
underscore (_) and dash (-) characters, but the first character of each parameter must 
be alphabetic. Upper and lower case characters are not considered distinct. For 
example: ANIMAL.DCL. IND would indicate node ANIMAL in the DCL lab (domain) 
of the IND division (organization). 
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Syntax Conventions 

The the syntax conventions used in this chapter are described below: 

■ Constant names defined in the C include file /usr/i ncl ude/sys/ns_i pc. h are 
included in the parameter descriptions for calls that can use them. 

■ A section titled “Programming Considerations” is included at the end of each 
NetIPC call reference page. This section consists of a table that lists the type 
definitions and passing modes that must be used for each call parameter. This table 
includes information for the C, Pascal, and FORTRAN programming languages. 
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NetIPC Reference Pages 

The following reference pages provide syntax and usage information for each of the 
NetIPC calls. The reference pages are organized alphabetically by NetIPC call name. 


Note Standard HP-UX “manual reference page” versions of the following 
NetIPC reference pages are also provided on-line and in the LAN 
Reference Pages manual (for the Series 600/800) and the Network Services 
Reference Pages manual (for the Series 300). 
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addoptO 

Adds an argument and its associated data to the opt parameter. 


Syntax 


addopt( opt , argnum , optioncode,data 1ength , data,result) 


Parameters 

opt 

argnum 
optioncode 

data!ength 

data 

result 


The opt parameter to which you want to add an argument. 
Refer to “NetIPC Common Parameters” for information on 
the structure and use of this parameter. 

The number of the argument to be added. The first 
argument is number zero. 

The option code or constant definition (C programs only) 
for the argument to added. These codes are described in 
each NetIPC call opt parameter description. 

The length in bytes of the data to be included. This 
information is provided in each NetIPC call opt parameter 
description. 

An array containing the data associated with the argument. 
The error code returned; zero or NSRNOERROR if no error. 


Description 

The addopt () call adds an argument and its associated data to an option buffer. The 
parameter must be initialized by i n i topt () before arguments can be added. 

The following C program fragment illustrates the use of ini topt () and addopt () to 
initialize and add two arguments to the option parameter of an i pcconnect () call. 
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In this example, the opt parameter is used to specify a maximum send size and 
maximum receive size of 1000 bytes. (Maximum send size indicates the maximum 
number of bytes that you expect to send with a single i pcsend (); addopt () call and 
maximum receive size indicates the maximum number of bytes you expect to receive 
with a single i pcrecv () call.) The opt parameter is assumed to be previously defined 
as an array of short integers. 


Note In the following example, it is assumed that the opt and data parameters 
were previously declared as arrays of short (16-bit) integers. Refer to 
“Opt Parameter Structure” earlier in this chapter for more information 
about the opt parameter. 
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addopt Example 

/* initopt initializes the opt parameter to contain two */ 
/* arguments one for the maximum send size and one for */ 
/* the maximum receive size. */ 

optnumarguments = 2; 
initopt (opt, optnumarguments, &error); 


/* perform error checking here */ 


/* addopt is called to add the maximum send size. The data */ 
/* parameter contains the value 1000. The data parameter */ 
/* was previously declared as an array of short integers. Note*/ 
/* that the first argument is number zero. */ 

argnum = 0; 

optioncode = NS0_MAX_SEND_SIZE; 
data length = 2; 
data[0] = 1000; 

addopt (opt, argnum, optioncode, data length, data, &error); 
/* addopt is called once more to add the maximum receive size */ 

/* Note that the data and datalength parameters are unchanged.*/ 

argnum = 1; optioncode = NS0_MAX_RECV_SIZE; 

addopt (opt, argnum, optioncode, datalength, data, &error); 


/* perform error checking here */ 

/* ipcconnect can now be called with the opt parameter. */ 



Programming Considerations 

The following is a list of the type definitions and passing modes for the addopt () call 
parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

opt 

short int 

°p‘D 

array of bytes 
by reference 

array of integers 
by reference 

argnurn 

short int 
argnum 

intl6* 
by value 

integer 
by value 

optioncode 

short int 
optioncode 

intl6* 
by value 

integer 
by value 

datalength 

short int 
datalength 

intl6* 
by value 

integer 
by value 

data 

short int dataj] 

intl6* 

by reference 

array of integers 
by reference 


*int!6 is a user-defined Pascal type for a 16-bit integer. 
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initoptO 

Initializes the opt parameter so that arguments can be added. 

Syntax 

initopt(opt, optnumarguments, result) 


Parameters 

opt The opt parameter to be initialized. Refer to “NetIPC 

Common Parameters” for information on the structure and 
use of this parameter. 

optnumarguments The number of arguments that will be placed in the opt 

parameter. If this parameter is zero, the opt parameter will 
be initialized to contain zero arguments. 

resu 11 The error code returned; zero or NSR_N0_ERR0R if no error. 

The ini topt () call must be used to initialize the opt parameter prior to adding 
arguments to it with addopt (). The optnumarguments parameter specifies how 
many arguments can be placed in the opt parameter. For example, if zero is 
specified, no arguments can be added to the opt parameter; if three is specified, three 
arguments must be added. 

In the following C program fragment, the same opt parameter is prepared for use in 
two different i pcconnect () calls. The first call will request a connection with the 
default maximum send and receive sizes (100 bytes), so its option parameter is 
initialized to contain zero arguments. The second i pcconnect () call will request a 
connection with a maximum send and receive size of 1000 bytes. Thus, its option 
parameter must be initialized to contain two arguments, the first to contain the 
maximum send size, and the second to contain the maximum receive size. 
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Note In the following example, it is assumed that the opt and data parameters 
have been previously declared as arrays of short (16-bit) integers. Refer to 
the section titled “Opt Parameter” earlier in this chapter for more 
information about the opt parameter. 


/* initopt initializes the opt parameter to be used in an */ 

/* ipcconnect call to contain zero entries. This will cause */ 
/* the maximum send and receive sizes to default to 100 bytes.*/ 

optnumarguments = 0; 

initopt (opt, optnumarguments, Serror); 


/* perform error checking here */ 


/*initopt reinitializes the opt parameter to be used in another*/ 
/*ipcconnect call. This call specifies the maximum */ 

/*send and receive sizes, so it must be initialized to contain*/ 
/*two arguments. */ 

optnumarguments = 2; 

initopt (opt, optnumarguments, &error); 


/* perform error checking here */ 
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/*The addopt call is used to add the maximum send size argument*/ 
/*as the first argument to the opt parameter. The maximum*/ 

/*send size has an option code of 3. The data parameter has been */ 
/*previously declared as an array of short integers and contains*/ 
/*the value 1000. Note that the first argument is number zero.*/ 

argnum = 0; 

optioncode = NS0_MAX_SEND_SIZE; 
data length = 2; 
data[0] = 1000; 

addopt (opt, argunm, optioncode, datalength, data, &error); 


/* perform error checking here */ 


/*addopt is used again to add the maximum receive size as the*/ 
/*second argument to the opt parameter. The maximum receive */ 
/*size has an option code of 4. The data parameter contains */ 
/* the value 1000. */ 

argnum = 1; 

optioncode = NS0_MAX_RECV_SIZE; 

addopt (opt, argnum, optioncode, datalength, data, Serror); 


/* perform error checking here */ 

/* ipcconnect can now be called using the opt parameter. */ 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the i ni topt () 
call parameters in C, Pascal, and FORTRAN. 

Parameter C PASCAL FORTRAN 

opt short int optQ array of bytes array of integers 

by reference by reference 

optnumarguments short int intl6* integer 

optnumarguments by value by value 

error short int * error intl6* integer 

by reference by reference 

*intl6 is a user-defined Pascal type for a 16-bit integer. 
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ipcconnect() 

Requests a connection to another process. 


Syntax 


i pcconnect [call desc , destdesc,flags, opt , vcdesc , resul t ) 

Parameters 

ca 1 Idesc Call socket descriptor. Refers to a call socket owned by the 

calling process. This parameter is optional; -1 or 
NS_NULL-DESC is allowed. 

destdesc Destination descriptor. Refers to a structure that indicates 

the location of the destination call socket (this is the call 
socket to which the connection request will be sent). A 
destination descriptor can be obtained by calling 
ipclookupO or ipcdest(). 

flags This parameter must be 0 or a pointer to 0. All other values 

are reserved for future use. (Refer to “Flags Parameter” 
for more information on the structure of this parameter.) 

opt Refer to “Opt Parameter” for information on the structure 

and use of this parameter. The following options are 
defined for this call: 

• optioncode = NSO_MAX_SEND_SIZE (code 3), 

datalength = 2. A two-byte integer that specifies the 
maximum number of bytes expected to be sent with a 
single i pcsend () call on this connection. 32,767 bytes 
can be specified. 
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Default: The TCP default is 100 bytes. If this option is 
not specified, i pcsend () will return an error if a call 
attempts to send greater than 100 bytes. 

• opt i oncode = NS0_MAX_RECV_S IZE (code 4), 

datal ength = 2. A two-byte integer that specifies the 
maximum number of bytes expected to be received with 
a single i pcrecv( ) call on this connection. 32,767 
bytes can be specified. Default: The TCP default is 100 
bytes. If this option is not specified, i pcrecv () will 
return an error if a call attempts to receive greater than 
100 bytes. 

vcdesc VC socket descriptor. Refers to a VC socket that is the 

endpoint of the virtual circuit connection at this node. May 
be used in subsequent NetIPC calls to reference the 
connection. 

result The error code returned; zero or NSRN0ERR0R if no error. 

Description 

The i pcconnect () call is used to initiate a virtual circuit on which data may be sent 
and received, i pcconnect ( ) reports only whether a virtual circuit has been initiated , 
not whether it was successfully established. A successful return only indicates that a 
connection request was sent without error. If the connection is successfully initiated, 
i pcconnect () will return a VC socket descriptor in its vcdesc parameter. This VC 
socket descriptor refers to a VC socket that is the endpoint of the virtual circuit at the 
local node. 

Actively establishing a virtual circuit with NetIPC calls is a three-step process: 

■ First, i pcconnect ( ) is called to request a connection on the client. 

■ Second, i pcrecvcn () is called to receive the connection request on the server. 

■ Third, i pcrecv () is called to find out if the virtual circuit connection initiated with 
i pcconnect () can be successfully established by the client. 
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i pcconnect ()'s opt parameter specifies the maximum number of bytes expected to 
be sent and received on the connection. The default for both sending and receiving is 
100 bytes. This information is passed to the underlying protocol. When TCP is the 
underlying protocol it will be used to limit the number of bytes which can be queued 
on a socket. 


Note When a process calls i pcconnect (), TCP checksumming for the 
connection that will be established is automatically enabled. TCP 
checksum is performed in addition to data link checksum. 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the 
i pcconnect () call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

calldesc 

ns_int_t calldesc 

integer 
by value 

integer*4 
by value 

destdesc 

ns_int_t 

destdesc 

integer 
by value 

integer*4 
by value 

flags 

ns_int_t *flags 

boolean array 
by reference 

integer*4 
by reference 

opt 

short int opt[| 

packed array of 
bytes 

by reference 

array of 16-bit 
integers 
by reference 

vcdesc 

ns_int_t *vcdesc 

integer 
by reference 

integer*4 
by reference 

result 

ns_int_t *result 

integer 
by reference 

integer*4 
by reference 


Cross-System Considerations 

Checksumming - When the i pcconnect () call is executed on the HP 9000 node, 
checksumming is enabled for the HP 9000-to-HP 1000 connection, HP 9000-to-HP 
3000 connection, or HP 9000-to-PC connection. 

Send and Receive sizes - The HP 1000 send and receive size range is 1 to 8,000 bytes; 
the HP 9000 send and receive size range is 1 to 32,767 bytes; the HP 3000 send and 
receive size range is 1 to 30,000 bytes; and the PC range is 1 to 65,535 bytes. 
Although the ranges are different, specify a buffer size within the correct range for 
the respective system. 
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ipccontrolO 

Performs special operations on sockets. 


Syntax 


ipccontrol (descriptor,request,wrtdata,wlen, readdata , rlen , 
flags,result) 


Parameters 

descriptor The descriptor that refers to the socket to be manipulated. 

The descriptor is either the vcdesc parameter returned 
from the i pcconnect or i pcrecvcn calls or the call 
descriptor returned from ipccreate. If request is set to 
NSC_GET_NODE_NAME, you must specify NS_NULL_DESC or 
-1 in this parameter. 

request Request code. Defines which operation is to be performed. 

May be one of the following: 

• NSC_NBIO_ENABLE (code 1). Place the socket 
referenced in the descriptor parameter in 
asynchronous mode. (Refer to “Synchronous and 
Asynchronous Socket Modes” in the “NetIPC 
Concepts” chapter for more information on 
asynchronous I/O.) 

• NSC_NBIO_DISABLE (code 2). Place the socket 
referenced in the descriptor parameter in 
synchronous mode. (Refer to “Synchronous and 
Asynchronous Socket Modes” in the “NetIPC 
Concepts” chapter for information on synchronous I/O.) 

• NSC_TIMEOUT_RESET (code 3). Change the referenced 
socket’s synchronous time-out. The default time-out 
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value is 60 seconds. The time-out value is given in 
tenths of seconds. (For example, a value of 1200 would 
indicate 120 seconds.) The new time-out value is 
treated as a 16-bit signed integer and must be placed in 
the first two bytes of the wrtdata parameter. The 
time-out value must be in the range of zero to 32767. 
Negative values have no meaning and will result in error. 
A value of zero sets the time-out to infinity. The 
time-out will not be reset if the referenced socket is 
switched to asynchronous mode and then back to 
synchronous mode. 

NSC_TIMEOUT_GET (code 4). Return the synchronous 
time-out value for the socket referenced in the 
descriptor parameter. The time-out value is treated 
as a 16-bit signed integer and is returned in the 
re add at a parameter. 

NSC_RECV_THRESH_RESET (code 1000). Change the 
read threshold of the VC socket referenced in 
descriptor parameter. (Read thresholds are one byte 
by default) The descriptor parameter must reference 
a VC socket descriptor. The new read threshold value 
must be placed in the first two bytes of the wrtdata 
parameter. Refer to “Asynchronous and Synchronous 
Socket Modes” in the “NetIPC Concepts” chapter for 
more information on read thresholds. 

NSC_SEND_THRESH_RESET (code 1001). Change the 
write threshold of the VC socket referenced in the 
descriptor parameter. (Write thresholds are one byte 
by default.) The descriptor parameter must reference 
a VC socket descriptor. The new write threshold value 
must be placed in the first two bytes of the wrtdata 
parameter. Refer to “Asynchronous and Synchronous 
Socket Modes” in the “NetIPC Concepts” chapter for 
more information on write thresholds. 



• NSC_RECV_THRESH_GET (code 1002). Return the 
current write threshold for the VC socket referenced in 
the descriptor parameter. The descriptor 
parameter must reference a VC socket descriptor. The 
write threshold is treated as a 16-bit signed integer and 
is returned in the readd at a parameter. 

• NSC_$END_THRESH_GET (code 1003). Return the 
current read threshold for the VC socket referenced in 
the descriptor parameter. The descriptor 
parameter must reference a VC socket descriptor. The 
read threshold is treated as a 16-bit signed integer and is 
returned in the re add at a parameter. 

• NSC_GET_N0DE_NAME (code 9008). Return the 
fully-qualified local node name. The node name is 
returned in the readdata parameter. 


wrtdata 

A data buffer or data vector used to pass time-out and 
threshold information. (Refer to “Data Parameter” for 
information on the structure of this parameter.) 

wlen 

Length in bytes of the wrtdata data buffer. 

readdata 

A data buffer or data vector used to contain any data 
returned by the call. (Refer to “Data Parameter” for 
information on the structure of this parameter.) 

rlen 

(input/output) 

The length in bytes of the readdata data buffer. On 
output, this parameter will contain the total number of bytes 
returned to the process. 

flags 

Refer to “Flags Parameter” for more information on the 
structure and use of this parameter. This parameter must be 
zero or a pointer to zero. All other values are reserved for 
future use. 

result 

The error code returned; zero or NSR N0 ERR0R if no error. 
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Description 

The i pccontrol () call is used to manipulate sockets in special ways. The type of 
request is specified by placing a certain request code in the request parameter. 
Although all of the request types require the descriptor , request and result 
parameters, some of the parameters are meaningless for certain requests. If 
NSCTIMEOUTRESET, NSC_RECV_THRESH_RESET or NSC_SEND_THRESH_RESET is 
specified, the wrtdata and wlen parameters are used. If NSC_TIMEOUT_GET, 
NSCRECVTHRESHGET, NSC_SEND_THRESH_GET or NSC_GET_NODE_NAME is 
specified, the readdata and rlen parameters are used. 


Sockets with Multiple Descriptors 

Because the i pccontrol () requests operate on sockets, all processes that own 
descriptors to a particular socket will be affected by i pccontrol () operations 
performed on that socket. 

For example, one process can change a socket’s read or write threshold, synchronous 
time-out interval or synchronous/asynchronous mode while another process is reading, 
writing or selecting on that socket. Exactly when the process that is sharing the 
socket will be affected by these operations cannot be reliably predicted. Reads, writes 
and selects in progress may complete using either previous, new or a combination of 
the previous and new values. 
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Programming Considerations 

When using the NSC_TIMEOUT_RESET or NSC_RECV_THRESH_RESET request, you 
must be sure to place the time-out value or write threshold value in the first two bytes 
of the wrtdata parameter. The following C program fragment demonstrates how this 
can be achieved: 

char wrtdata[128] 

*(short*)&wrtdata = 600; 

ipccontrol(descriptor,NSC_TIME0UT RESET,&wrtdata,2,0,0,&f1 ags,&result 

); 

The following is a list of the type definitions and passing modes for the 
i pccontrol () call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

descriptor 

ns_int_t 

descriptor 

integer 
by value 

integer*4 
by value 

request 

ns_int_t request 

integer 
by value 

integer* 4 
by value 

wrtdata 

char *wrtdata 

packed array of 
characters 
by reference 

array of 
characters 
by reference 

wlen 

ns_int_t wlen 

integer 
by value 

integer*4 
by value 

readdata 

char *readdata 

packed array of 
characters 
by reference 

array of 
characters 
by reference 

rlen 

ns_int_t *rlen 

integer 
by reference 

integer*4 
by reference 

flags 

ns_int_t *flags 

boolean array 
by reference 

integer*4 
by reference 

result 

ns_int_t *result 

integer 
by reference 

integer*4 
by reference 
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ipccreateO 

Creates a call socket. 


Syntax 


ipccreate( socketkind,protoco 7, flags , opt ,ca 7 ldesc , resu11 ) 


Parameters 

socketkind Indicates the type of socket to be created. Must be 

NS_CALL or 3 to indicate a call socket. Other values are 
reserved for future use. 

protoco 7 Indicates the protocol module that the calling process wishes 

to access. If specified, can be NSP_TCP or 4 to indicate 
Transmission Control Protocol (TCP). If zero (0) is 
specified, TCP will always be chosen for call sockets. Other 
values are reserved for fiiture use. 

f 7 ags This parameter is reserved for future use. All bits must be 

clear (not set). (Refer to “Flags Parameter” section of this 
chapter for more information on the structure of this 
parameter.) 

opt Refer to the “Opt Parameter” section of this chapter for 

more information on the structure and use of this 
parameter. The following options are defined for this call: 

• optioncode = NSOMAXCONNREQBACK (code 6), 
datalength = 2. A two-byte integer that specifies the 
maximum number of unreceived connection requests 
that may be queued to a call socket. If this value is not 
specified, the default maximum will be used. Default: 
One request. Range: 1-20. (NOTE: A queue limit of 
one may be too few if many processes attempt to initiate 
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connections to the call socket simultaneously. If this 
occurs, some connection requests may be automatically 
rejected.) 

• optioncode = NSOPROTOCOLADDRESS (code 128), 
datalength = 2. A two-byte integer that specifies a 
TCP protocol address to be used by the newly-created 
call socket. If this option is not specified, or if zero is 
specified, NetIPC will dynamically allocate an address. 
You must be have superuser capability to request 
protocol addresses less than 1024. Recommended Range 
For Cross-System Applications: 30767 to 32767. 

ca 7 Idesc Call socket descriptor. Refers to the newly-created call 

socket. 

resu 11 The returned error code; zero or NSR_N0_ERR0R if no error. 


Description 

i pccreate () is used to create a call socket which will be used by subsequent NetIPC 
calls to establish a virtual circuit connection between two or more processes. When 
invoked successfully, i pccreate () returns a call socket descriptor that refers to the 
newly-created call socket. A process may own a maximum of 2048 descriptors, 
i pccreate () will return an error if a process attempts to exceed this limit. This limit 
includes files as well as socket descriptors and destination descriptors. These 
descriptors may reference sockets and/or files inherited by or otherwise opened by the 
process. 

The NSO PROTOCOL ADDRESS option (code 128) can be used to create a call socket 
with a specific protocol address. If this protocol address is known to the process’s 
peer, the peer process can call i pcdest () with this address (in i pcdest ()’s 
proto add r parameter) so that it may obtain a destination descriptor that references 
this call socket. Refer to the section titled “Connection Establishment Summary” in 
the “NetIPC Concepts” chapter for more information. 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the i pccreate () 
call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

socketldnd 

ns_int_t 

socketkind 

integer 
by value 

integer *4 
by value 

protocol 

ns_int_t protocol 

integer 
by value 

integer*4 
by value 

flags 

ns_int_t * flags 

boolean array 
by reference 

integer*4 
by reference 

opt 

short int optj] 

packed array of 
bytes 

by reference 

array of 
integers 
by reference 

calldesc 

ns _int_t 

*calldesc 

integer 
by reference 

integer*4 
by reference 

result 

ns_int_t *result 

integer 
by reference 

integer*4 
by reference 


Cross-System Considerations 

TCP Protocol Address - The HP 9000, HP 1000, HP 3000, and PC implementations 
of i pccreate () support different ranges of permitted TCP protocol addresses that 
can be specified in the opt parameter. All systems should specify a TCP protocol 
address within the range 30767 to 32767 decimal for cross-system use. 
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ipcdestO 

Creates a destination descriptor. 


Syntax 


ipcdest {socketkind,nodename , node! e/7, protocol,protoaddr, 
proto! ertyfl ags ,opt , destdesc , resu 11 ) 


Parameters 

socketkind 


nodename 


nodelen 


protocol 


proto addr 


Defines the type of socket. Must be NS_CALL or 3 to 
specify a call socket. Other values are reserved for future 
use. 

The ASCII-coded name that identifies the node where the 
call socket that uses proto addr resides. 

Default: You may omit the organization, organization and 
domain, or all parts of the node name. When organization 
or organization and domain are omitted, they will default to 
the local organization and/or domain. If the nodelen 
parameter is set to zero, node name is ignored and the node 
name defaults to the local node. 

The length in bytes of nodename. If this parameter is set to 
zero (0), the nodename parameter is ignored and the node 
name defaults to the local node. A fully-qualified node 
name may be 50 bytes long. 

Defines the Transport Layer protocol to be used. Must be 
NSP_TCP or 4 to indicate the Transmission Control Protocol 
(TCP). Other values are reserved for future use. 

A data buffer containing the TCP protocol address specified 
in the remote process’s ipccreate() call. 
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proto!en 

The length in bytes of the protocol address. TCP protocol 
addresses are two bytes long. 

flags 

This parameter is reserved for future use. Refer to the 
“Flags Parameter” section of this chapter for information on 
the structure of this parameter. 

opt 

No options are defined for this call. Refer to the “Opt 
Parameter” section of this chapter for information on the 
structure and use of this parameter. 

destdesc 

Destination descriptor. Describes the destination call 
socket. May be used in a subsequent i pcconnect () call to 
establish a connection to another process. 

result 

The error code returned; zero or NSR_N0_ERR0R if no error. 


Description 

The i pedest () call creates a destination descriptor that the calling process can use 
to establish a connection to another process. 

This call is similar in function to i pci ookup () because it returns a destination 
descriptor. However, because ipcdest() allows you to specify a protocol address, it 
allows you to obtain a destination descriptor for a call socket with a particular protocol 
address. A call socket can be created with a particular protocol address by using the 
ipccreate() call with the NS0_PR0T0C0L_ADDRESS option. 

The i pedest () call does not verify that the remote endpoint described by the input 
parameters exists. This evaluation is delayed until the destination descriptor is used in 
a subsequent i pcconnect () call. Refer to Chapter One for more information on 
using i pedest () to establish a connection. 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the i pcdest () 
call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

socketkind 

ns_int_t 

socketkind 

integer 
by value 

integer*4 
by value 

nodename 

char *nodename 

packed array of 
characters 
by reference 

array of 
characters 
by reference 

nodelen 

ns_int_t nodelen 

integer 
by value 

integer*4 
by value 

protocol 

nsjntj: protocol 

integer 
by value 

integer*4 
by value 

protoaddr 

short int 
*protoaddr 

packed array of 
intl6* 

by reference 

array of integers 
by reference 

protolen 

ns_int_t protolen 

integer 
by value 

integer*4 
by value 

flags 

ns_int_t * flags 

boolean array 
by reference 

integer*4 
by reference 

opt 

short int opt|] 

packed array of 
bytes 

by reference 

array of integers 
by reference 

destdesc 

ns_int_t 

*destdesc 

integer 
by reference 

integer*4 
by reference 

result 

ns_int_t *result 

integer 
by reference 

integer*4 
by reference 

*int!6 is a user-defined Pascal type for 

a 16-bit integer. 
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ipcerrmsgO 

Provides text describing NetlPC error. 

Syntax 

ipcerrmsg (error, buffer. Ten, result) 


Parameters 

error The number of the NetlPC error being described. 

buffer The data buffer that will hold the description. 

len A pointer to the buffer length. On output, it will contain 

the length of the description. 

resu 11 The error code returned; zero or NSR_N0_ERR0R 


Description 

ipcerrmsg copies an error message for a NetlPC error into a supplied buffer. It will 
copy len-1 bytes into the buffer. The result will be NULL terminated. If the error 
number passed in is not a recognized NetlPC error number, then NSRERRNUM (value 
85) is returned. 


ipcerrmsgO Example 

#define BUFLEN 80 

char buffer [BUFLEN]; 

ipcsend ( ,&result) 

if (result != NSR_N0_ERR0R) 

ipcerrmsg (result,buffer,BUFLEN,result2); 

printf ("NetlPC error %od = %os\n", result, buffer); 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the i pcerrmsg () 
call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

error 

short int *error 

intl6* 

by reference 

integer 
by reference 

buffer 

char *buffer 

packed array of 
character by 
reference 

array of characters 
by reference 

len 

ns_int_t len 

integer 
by value 

integer *4 
by value 

result 

ns _int_t ^result 

integer 
by reference 

integer *4 
by reference 


*intl6 is a user-defined Pascal type for a 16-bit integer. 
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ipcerrstrO 

Provides text describing NetlPC error numbers. 


Syntax 


ipcerrstr (error) 


Parameters 

error The error code returned from a NetlPC system call; zero or 

NSR_N0_ERR0R if no error. 


Description 

ipcerrstr takes a NetlPC error number as input and returns a pointer to a NULL 
terminated string describing the error. 


ipcerrstrQ Example 

ipcsend ( ,&result); 

printf ("NetlPC error %d = %s\n", result, ipcerrstr 
(result)); 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the i pcerrstr () 
call parameters in C, Pascal, and FORTRAN. 

Parameter C PASCAL FORTRAN 

error short int *error intl6* integer 

by reference by reference 

*intl6 is a user-defined Pascal type for a 16-bit integer. 
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ipcgetnodenameO 

Obtains NetIPC node name of current host. 


Syntax 


ipcgetnodename (nodename,size,result) 


Parameters 

nodename The pointer to the character array in which the 

ASCII-coded NetIPC node name is to be returned. 

size The length in bytes of the nodename array on input and the 

length of the returned NetIPC node name on output 

resu 11 The error code returned; zero or NSR_N0_ERR0R if no error. 

Description 

The i pcgetnodename( ) call is used to obtain the NetIPC node name for the current 
processor as set by setnodename (2). The name is returned in the array to which the 
nodename parameter points. 
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ipcIookupO 

Obtains a destination descriptor. 


Syntax 


ipciookup ( socketname,nlen,nodename,node Ten,flags , 
destdesc,protocol,socketkind,result) 


Parameters 

socketname The name of the call socket to be “looked up.” Upper and 

lower case characters are not considered distinct. Refer to 
“Socket Name Parameter” for a detailed discussion of 
naming. 

nlen The length of the socket name in characters. Maximum 

length is 16 characters. 

nodename The ASCII-coded name that identifies the node where the 

socket specified in the socketname parameter resides. 
(Refer to “Node Name Parameter” for the syntax of this 
parameter.) 

Default: You may omit the organization, organization and 
domain, or all parts of the node name. When organization 
or organization and domain are omitted, they will default to 
the local organization and/or domain. If nodelen is set to 
zero, nodename is ignored and the node name defaults to 
the local node. 

nodelen The length in bytes of the nodename parameter. If zero (0) 

is specified, NetIPC will search the local node’s socket 
registry. (See the node name parameter above for more 
information.) 
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flags 


destdesc 


protocol 
socketkind 

result 


This parameter is reserved for future use. All bits must be 
clear (not set). (Refer to the “Flags Parameter” section of 
this chapter for more information on the structure of this 
parameter.) 

Destination descriptor. Refers to the descriptor which 
indicates the location of the named call socket May be 
used in subsequent ipcconnect and ipcname NetIPC calls. 

This parameter is reserved for future use. Zero (0) is always 
returned to this parameter. 

Identifies the socket’s type. Will always be 3 to indicate a 
call socket. 

The error code returned; zero or NSR_N0_ERR0R if no error. 


Description 

The i pci ookup() call is used to obtain a destination descriptor for a named call 
socket. When supplied with valid socket and node names, it looks up the call socket 
in the socket registry at the node specified in the nodename parameter and returns a 
destination descriptor that can be used by subsequent NetIPC calls to locate the call 
socket. A destination descriptor is required by the i pcconnect call to provide the 
information necessary to direct a connection request to the proper node and call 
socket and thus initiate a connection. 


Timing Problems 

When a process attempts to look up a socket name in the appropriate socket registry, 
the name must be there or a NSR_NAME_N0T_F0UND (code 37) error will be returned 
to the calling process. When two processes are running concurrently, it may be 
difficult to ensure that a socket name is placed in the socket registry prior to being 
“looked up” by another process. 
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In order to avoid a timing problem: 

■ The process that calls i pci ookup () can test for a NSR_NAME_NOT_FOUND (code 
37) error in the call’s result parameter. If this error is returned, the process can 
try again by entering a loop and repeating the i pci ookup () call for a specified 
number of times. 

■ The process could also call si eep () to suspend execution for an interval and then 
repeat the i pci ookup () call. (Refer to the HP-UX Reference Manual for more 
information on sleep(3c)). 

■ The process that calls i pcname () can name its call socket and then schedule the 
process that calls i pci ookup (). 


Note On the Series 600/800 only, i pci ookup () implementations between 

HP-UX software versions 1.0 and later software versions are incompatible. 
If you must use NetIPC to communicate between HP-UX software 
versions 1.0 and later software versions, utilize the i pedest () system call, 
not ipclookup(). 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the i pci ookup () 
call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

socketname 

ns_int_t 

socketname 

packed array of 
characters 
by reference 

array of 
characters 
by reference 

nlen 

ns _int_t nlen 

integer 
by value 

integer*4f 
by value 

nodename 

char *nodename 

packed array of 
characters 
by reference 

array of 
characters 
by reference 

nodelen 

ns_int_t nodelen 

integer 
by value 

integer*4 
by value 

flags 

ns_int_t *flags 

boolean array 
by reference 

integer*4 
by reference 

destdesc 

ns_int_t 

*destdesc 

integer 
by reference 

integer*4 
by reference 

protocol 

ns _int_t *protocol 

integer 
by reference 

integer*4 
by reference 

socketkind 

ns_int_t 

*socketkind 

integer 
by reference 

integer*4 
by reference 

result 

ns _int_t *result 

integer 
by reference 

integer*4 
by reference 
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ipcnameO 

Associates a name with a call socket or destination descriptor. 


Syntax 


ipcname (descriptor,socket name,nlen , resu11) 


Parameters 

descriptor 

socketname 

(input/output) 


nlen 


result 


The descriptor that references the call socket to be named. 
May be a call socket descriptor or a destination descriptor. 

The ASCII-coded name to be associated with the descriptor. 
Upper and lower case characters are considered equivalent. 
NetIPC can also return a randomly-generated name in this 
parameter (see nlen). Refer to “Socket Name Parameter” 
for a detailed discussion of naming. 

The length in characters of socketname. Maximum length 
is 16 characters. If zero is specified, NetIPC will return a 
random, eight-byte name in the socketname parameter. 

The eight-byte length is not returned in the nlen parameter. 

The error code returned; zero or NSR NO ERROR if no error. 


Description 

i pcname () associates a name with a call socket and adds this information to the local 
node’s socket registry. 

The name a process associates with a call socket must be known to its peer process so 
that the peer process may look up the name with an i pci ookup () call. This may be 
accomplished by hard-coding the name into both processes or by passing the name 
from one process to another. 


NetIPC Calls 3-51 






The name associated with a call socket can be user-defined or randomly generated by 
NetIPC and must be unique to your node (i.e., it cannot be simultaneously associated 
with two descriptors.) For example, if a call socket is assigned the name “Liz” with a 
call to i pcname(), a subsequent call with “Liz” will result in an error. You can 
ensure that the name you assign to a call socket is unique by using the random name 
generating feature of i pcname (). A name can be reused only if it is not currently 
being used, but a call socket may be listed under multiple names. 

Under most circumstances, i pcname () should be called with a name and the call 
socket descriptor that refers to a call socket owned by the calling process. If the call 
completes successfully, the call socket will be listed in the socket registry at the local 
node, i pci ookup () can be called from another process to “look up” the socket 
name in the local node’s socket registry. 

i pcname () always enters its listings into the local node’s socket registry, 
i pci ookup(), by contrast, can look up socket names at both the local node and at a 
remote node. Because “long distance” look-ups take longer than local look-ups, it 
may be helpful to use i pcname() to name destination descriptors. When a process 
names a destination descriptor, the name of the descriptor is placed in the local 
socket registry (the socket registry at the node where the calling process resides). 

This allows other processes to look up the name in the local socket registry rather 
than calling i pci ookup () to look up the name in a socket registry at a remote node. 

Using i pcname () to name a destination descriptor is less reliable than looking up the 
socket name at the remote node because destination descriptors, like telephone 
numbers, can become outdated. As a precaution, you should periodically refresh 
locally stored destination descriptors. 


Note You cannot use i pcname () to name VC sockets. 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the i pcname () 
call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

descriptor 

ns_int_t 

descriptor 

integer 
by value 

integer*4 
by value 

socketname 

char *socketname 

packed array of 
characters 
by reference 

array of 
characters 
by reference 

nlen 

ns _int_t nlen 

integer 
by value 

integer*4 
by value 

result 

ns_int_t * result 

integer 
by reference 

integer*4 
by reference 
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ipcnamerase() 

Deletes a name associated with a call socket or destination call socket. 


Syntax 


ipcnamerase (socket name,nlen , result) 


Parameters 

socketname The ASCII-coded name that was previously associated with 

a call socket descriptor or destination descriptor via 
i pcname (). Upper and lower case characters are considered 
equivalent. Refer to “Socket Name Parameter” for a 
detailed description of naming. 

nlen The length in bytes of the specified name. Maximum length 

is 16 bytes. 

result The error code returned; zero or NSRNOERROR if no error. 


Description 

i pcnamerase () can be called to remove listings from the local node’s socket registry. 
Only the owner of a call socket or destination call socket may remove the socket’s 
name from the local socket registry. (Refer to “Socket Ownership” in the “NetIPC 
Concepts” chapter for the definition of a socket owner.) A process that attempts to 
erase the name of a socket it does not own will receive an NSR_NO_OWNERSHIP (code 
38) error. 

If a call socket descriptor or destination descriptor is destroyed via i pc shutdown (), 
or if its sole owner terminates, then any listings for it that exist at the local socket 
registry are automatically purged. 

When multiple processes have descriptors for the same socket, the first 
i pcnamerase () call will succeed, but subsequent calls will fail. 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the 
ipcnamerase() call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

socketname 

char *socketname 

packed array of 
characters 
by reference 

array of 
characters 
by reference 

nlen 

ns_int_t nlen 

integer 
by value 

integer*4 
by value 

result 

ns_int_t ^result 

integer 
by reference 

integer*4 
by reference 
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ipcrecvO 

Checks the status of a connection or receives data on an established connection. 


Syntax 


ipcrecv( vcdesc>data,dlen,flags , opt , resuIt) 


Parameters 

vcdesc 


data 


dlen 

(input/output) 


VC socket descriptor. Refers to a VC socket that: (1) is the 
endpoint of a virtual circuit connection that has not yet 
been established, or (2) is the endpoint of an established 
virtual circuit on which data will be received. 

A data buffer that will hold the received data, or a data 
vector describing the location where the data is to be placed. 
Refer to “Data Parameter” for information on the structure 
and use of this parameter. 

If the data parameter is a data buffer, dlen is the maximum 
number of bytes you are willing to receive. If the 
NSF_DATA_WAIT flag is set, the amount of data should be 
75% if the maximum amount receivable. If the data 
parameter is a data vector, dlen refers to the length of the 
data vector in bytes. As a return parameter, dlen indicates 
how many bytes were actually received. If i pcrecv () is 
used to check the status of a connection (not to receive 
data), the dlen parameter is meaningless on input and a 
value of zero (0) is returned on output. 
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flags 

(input/output) 


Refer to the “Flags Parameter” section of this chapter for 
more information on the structure and use of this 
parameter. Although flags may be set on the first 
i pcrecv( ) call, they won’t take effect until subsequent 
i pcrecv ( ) calls over the established connection. The 
following bits are defined for this call: 

• bit 20 — NSF_DATA_WAIT (input). When this bit is 
set, i pcrecv () will never successfully complete 
receiving less data than it requested in the dlen 
parameter. If this bit is not set, i pcrecv () may 
complete receiving less data than it requested in dlen. 
Refer to the discussion below for more information on 
this bit. This bit is only meaningful when i pcrecv () is 
issued against an established connection. 

• bit 26 — NSF_MORE_DATA (output). When set, this 
bit indicates that the data received was not delimited by 
an end-of-message marker. Since user processes always 
employ stream mode, this bit will always be set. (The 
Transmission Control Protocol decides how much data 
to transmit, but it does not delimit the data transmitted 
in the form of an individual message.) 

• bit 30 — NSF_PREVIEW (input). When set, this bit 
allows you to preview the data queued on the 
connection. Data is placed in the data parameter but 
not dequeued from the connection. Because the data is 
not dequeued, the next i pcrecv () call will read the 
same data. This bit is only valid when i pcrecv () is 
issued against an established connection. 
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• bit 31 — NSF_VECTORED (input). When set, this bit 
indicates that the data parameter is a data vector and 
not a data buffer. This bit is only valid when i pcrecv () 
is issued against an established connection. 

opt An array of options and associated information. Refer to 

“NetlPC Common Parameters” for information on the 
structure and use of this parameter. The following option is 
defined for this call: 

• optioncode = NSO_DATA_OFFSET (code 8), 
datalength = 2. A two-byte integer that defines a byte 
offset from the beginning of a data buffer where NetEPC 
is to begin placing the data. This option is valid only if 
the data parameter is a data buffer and not a data 
vector. 

resu 7 1 The error code returned; zero or NSR_N0_ERR0R if no error. 

Description 

i pcrecv () has two functions: 

■ Check the status of a connection that was initiated with i pcconnect (). 

■ Receive data on a previously established virtual circuit connection. 


Checking the Status of a Connection 

When i pcrecv () is called to check the status of a connection, a zero returned in the 
resu 11 parameter indicates that the call was successful and that a virtual circuit 
connection has been established. If a non-zero value is returned in the result 
parameter, the call was not successful. 

An i pcrecv () call can be unsuccessful for the following reasons: 

■ N$R_$0CKET_T IMEOUT Error Received. The synchronous timer expired before a 
“successful” connection status could be obtained. The connection is still pending 
and i pcrecv () should be called again. 
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■ NSRWOULDBLOCK Error Received. The VC socket referenced by i pcrecv () is in 
asynchronous mode and the call could not be satisfied. A connection is still pending 
and i pcrecv () should be called again. You can perform an exception select on 
the referenced socket to determine if a successful status can be obtained prior to 
calling i pcrecv(). (Refer to the discussion of i pcsel ect () later in this chapter 
for more information.) 

■ NSR SIGNALINDI CAT I ON Error Received. A signal indication was received. For 
more information on signals, refer to the discussion of signals in the “NetIPC 
Concepts” chapter. Signals are also described in the HP-UX Reference Manual. 

■ Other Errors. If i pcrecv () was unsuccessful for a reason other than those listed 
above, the referenced VC socket should be shut down by calling i pcshutdown (). 

Receiving Data 

When i pcrecv () is called to receive data queued on a previously established virtual 

circuit connection, several different alternatives are available: 

■ Normal reading. Data is dequeued from the connection and placed into the user’s 
buffer. 

■ Preview reading. This alternative is specified by setting the NSF_PREVIEW bit (bit 
30) of the fl ags parameter. When this bit is set, data is placed in the process’s 
buffer, but not dequeued from the connection. Consequently, the next i pcrecv () 
call will read the same data. Because NSF_PREVI EW enables a process to determine 
what a data buffer contains before actually reading it, it is especially useful to set 
this bit when the receiving process must assemble messages from the byte streams 
that it receives. For example, if the sending process places the length of its 
“message” in the first two bytes of its send buffer, the receiving process can use 
NSF PREVI EW to extract the length information from the data received. When the 
buffer is received again with a subsequent i pcrecv () call, the receiving process 
can specify this length information in the dlen parameter and thus reassemble the 
“message.” 

■ Vectored or “scattered” reading. The calling process may pass a data vector 
argument that describes one or more locations. Received data will be placed into 
these locations. This alternative can be used with both the normal and preview 
reads described above and is specified by setting the NSF_VECT0RED bit (bit 31) of 
the flags parameter. For vectored reads, an i ovec structure contains the data 
vector. An i ovec structure can be defined in C as: 
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struct iovec { 
char *iov_t>ase; 
unsigned iovjlen; 

}; 

and the normal type for the data argument can be replaced by struct i ovec 
*data. Each i ovec entry specifies the base address and length of an area in 
memory where the data should be placed. 

The i pcrecv () call functions differently depending on whether the socket 
referenced is in synchronous or asynchronous mode, and whether or not the 
NSFDATAWAIT bit (bit 20) is set in the flags parameter. 


Caution The NetIPC NSF_DATA_WAIT flag can cause a program to block for an 
extreme period of time (for example, eight minutes for 8 bytes). It is 
recommended that NetIPC programs implement a loop instead. Refer 
to the next paragraph for more specific loop information. 


A loop such as the following, instead of the NetIPC NSF DATA WAIT flag, should be 
implemented to prevent a NetIPC program to block for a long period of time: 

/* loop to receive 1000 bytes */ 

char data_array[1000]; 

char *copy_data_to; 

int bytesneeded = 1000; 

int bytesreceived = 0; 

/* stuff missing; eg ipccreate or ipcconnect, etc*/ 

copydatato = dataarray; 

while (bytesreceived < bytes_needed) { 

bytecount = bytes_needed - bytesreceived; 

/* NOTE: NSF_DATA_WAIT not set */ 

ipcrecv(__ start, bytecount,...); 

bytesreceived += byte_count; 
copydatato += bytecount; 

} 
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The following paragraphs describe how the i pcrecv () call functions depending on 
whether or not the socket referenced is in synchronous or asynchronous mode, and 
whether or not the NSF_DATA_WAIT flag is set. (When a socket is created, it is placed 
in synchronous mode by default. You can place a socket in asynchronous mode by 
calling i pccontrol (). Refer to the discussion of i pccontrol () earlier in this 
chapter for more information.) 


Note The “amount requested” by an i pcrecv () call refers to the number of 
bytes specified by the dien parameter or the amount specified in the data 
vector if the NSFVECTORED flag is set. 


■ Synchronous I/O, N$F_DATA_WAIT set If the socket referenced by i pcrecv () is 
in synchronous mode and the NSF_DATA_WAIT bit (bit 20) is set, the calling process 
will block until (1) the amount of data queued on the connection is greater than or 
equal to the amount requested, (2) the call times out, or (3) a signal is received. If 
the data queued on the connection is less than dien bytes, i pcrecv () will suspend 
the calling process and the synchronous timer will be set. If the timer expires 
before enough data arrives to satisfy the request, the calling process will resume and 
an NSR_S0CKET_TIME0UT error (code 59) will be returned indicating that a 
time-out occurred. (The synchronous time-out can be adjusted by calling 

i pccontrol () . Refer to the discussion of i pccontrol ( ) for more information.) 

■ Synchronous I/O, N$F_DATA_WAIT not set. If the socket referenced by 

i pcrecv () is in synchronous mode and the NSF_DATA_WAIT bit (bit 20) is not set, 
the the calling process will block until (1) some amount of data is queued on the 
connection (the amount of data queued may or may not be the amount requested, 
and may be as little as one byte), (2) the call times out, (3) a signal is received, or (4) 
the connection goes down. If no data is queued on the connection within the 
synchronous time-out period, the calling process will resume and an 
NSR SOCKET TIMEOUT error (code 59) will be returned indicating that a time-out 
occurred. 

■ Asynchronous I/O, NSF DATA WAIT set If the socket referenced by i pcrecv ( ) is 
in asynchronous mode and the NSF_DATA_WAIT bit is set, an NSRW0ULDBL0CK 
(code 56) error is returned to the calling process if the amount of data queued on 
the connection is less than the amount requested. The calling process is not 
suspended awaiting the arrival of data. You can perform a read select on the 
referenced socket by invoking i pcsel ect (). i pcsel ect () determines whether 
or not a socket is readable prior to calling i pcrecv () to receive data. (Refer to 
the discussion of i pcsel ect () later in this chapter or more information.) 
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■ Asynchronous I/O, N$F_DATA_WAIT not set If the socket referenced by 

i pcrecv( ) is in asynchronous mode and the NSF_DATA_WAIT bit is not set, as 
little as one byte of data will satisfy the i pcrec v () request. However, if no data is 
queued to the connection, an NSR_W0ULD_BL0CK error is returned. 

For a detailed discussion of asynchronous and synchronous I/O, refer to “Synchronous 
and Asynchronous Socket Modes’* in the “NetIPC Concepts” chapter. 


Programming Considerations 

The following is a list of the type definitions and passing modes for the i pcrecv () 
call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

vcdesc 

ns_int_t vcdesc 

integer 
by value 

integer*4 
by value 

data 

char *data 

packed array of 
characters 
by reference 

array of 
characters 
by reference 

dlen 

ns _int_t *dlen 

integer 
by reference 

integer*4 
by reference 

flags 

ns_int_t * flags 

boolean array 
by reference 

integer*4 
by reference 

opt 

short int opt[| 

array of bytes 
by reference 

array of integers 
by reference 

result 

ns_int_t *result 

integer 
by reference 

integer*4 
by reference 


Cross-System Considerations 

Receive size - The HP 1000 receive size range is 1 to 8,000 bytes, the HP 3000 is 1 to 
30,000 bytes, and the HP 9000 is 1 to 32,767 bytes. The maximum receive size of the 
data buffer determines the receive size buffer on the PC. 
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ipcrecvcnO 

Receives a connection request on a call socket. 


Syntax 


i pcrecvcn (ca 1 ldesc , vcdesc , flags , opt , resu 11) 


Parameters 

calldesc 

vcdesc 

flags 

opt 


Socket descriptor. Refers to a call socket owned by the 
calling process. 

VC socket descriptor. Refers to a VC socket that is the 
endpoint of the newly-established virtual circuit connection. 

Refer to “NetIPC Common Parameters” for more 
information on the structure of this parameter. No flags are 
defined for this call. 

Refer to “NetIPC Common Parameters” for information on 
the structure and use of this parameter. The following 
options are defined for this call: 

• optioncode = NSO_MAX_SEND_SIZE (code 3), 

datalength = 2. A two-byte integer that specifies the 
maximum number of bytes you expect to send with a 
single call to ipcsend() on this connection. Default: 
TCP default is 100 bytes. If this option is not specified, 
i pcsend () will return an error if a call attempts to send 
greater than 100 bytes. 
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• opti oncode = NSO_MAX_RECV_S IZ E (code 4), 

datalength = 2. A two-byte integer that specifies the 
maximum number of bytes you expect to receive with a 
single call to ipcrecv() on this connection. Default: 
TCP default is 100 bytes. If this option is not specified, 
i pcrecv () will return an error if a call attempts to 
receive greater than 100 bytes. 

resu 11 The error code returned; zero or NSR_N0_ERR0R if no error. 


Description 

When i pcrecvcn () is invoked successfully against a call socket that has queued 
connection requests, it returns a VC socket descriptor to the calling process. This VC 
socket descriptor can be used to specify the virtual circuit connection a process 
intends to send on, receive on, or shut down with subsequent NetIPC calls. 


Synchronous vs. Asynchronous i/O 

i pcrecvcn () functions differently depending on whether the call socket referenced 
is in synchronous or asynchronous mode. (When a socket is created, it is placed in 
synchronous mode by default. You can place a socket in asynchronous mode by 
calling ipccontrol (). Refer to the discussion of ipccontrol () earlier in this 
chapter for more information.) The following paragraphs describe these differences: 

■ Synchronous I/O. i pcrecvcn () will block when invoked against a call socket 
that has no queued connection requests if the socket is in synchronous mode. 
The calling process will resume execution when a connection request arrives, or 
after the synchronous time-out interval has expired. An i pcrecvcn () call will 
not block forever unless the synchronous time-out interval has been set to zero 
with an i pccontrol () call. 
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■ Asynchronous I/O. i pcrecvcn () will never block against sockets in 

asynchronous mode. When i pcrecvcn () is invoked against an asynchronous 
call socket that has no queued connection requests, a NSR_W0ULD_BL0CK (code 
56) is returned to the calling process. When i pcrecvcn () is used in this way, 
the calling process does not wait to receive a connection request. In order to 
determine when connection requests are present, a process can perform an 
exception select on the referenced call socket by calling i pcsel ect (). (Refer 
to the discussion of i pcsel ect () for more information.) 

For a detailed discussion of synchronous and asynchronous I/O, refer to “Synchronous 
and Asynchronous Socket Modes” in the “NetIPC Concepts” chapter. 


Note When a process calls ipc recvcn(), TCP checksumming for the 

connection that will be established is automatically enabled. TCP 
checksum is performed in addition to data link checksum. 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the i pcrecvcn () 
call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

calldesc 

ns_int_t calldesc 

integer 
by value 

integer*4 
by value 

vcdesc 

ns_int_t vcdesc 

integer 
by reference 

integer*4 
by reference 

flags 

ns_int_t *flags 

boolean array 
by reference 

integer*4 
by reference 

opt 

short int opt[j 

packed array of 
bytes 

by reference 

array of integers 
by reference 

result 

ns_int_t *result 

integer 
by reference 

integer*4 
by reference 


Cross-System Considerations 

Checksumming - When the i pcrecvcn () call is executed on the HP 9000 node, then 
checksumming is always enabled for the HP 9000-to-HP 1000 connection, HP 
9000-to-3000 connection, or HP 9000-to-PC connection. 

Send and Receive sizes - The HP 1000 send and receive size range is 1 to 8,000 bytes; 
the HP 9000 send and receive size range is 1 to 32,767 bytes; the HP 3000 send and 
receive size range is 1 to 30,000 bytes; and the PC range is 1 to 65,535 bytes. 

Although the ranges are different, specify a buffer size within the correct range for 
the respective system. 
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ipcselectO 

Determines the status of a call socket or VC socket 


Syntax 


ipcselect( sdbound , readmap . writemap , exceptionmap ,timeout, 
result) 


Parameters 

sdbound 

(input/output) 


readmap 

(input/output) 


Specifies the upper ordinal bound on the range of 
descriptors specified in the readmap, wri temap and 
except /onmap parameters. An i pcsel ect () call will be 
most efficient if this parameter is set to the maximum 
ordinal value of the sockets specified in these parameters. 
Because a NetIPC process may have concurrent access to a 
maximum of 2048 descriptors (descriptors 0 through 2047), 
sdbound may be given a maximum value of 2047. As an 
output parameter, sdbound contains the upper ordinal 
boundary of all of the descriptors that met the select criteria. 

A bit map indexed with NetIPC socket descriptors. On 
input, this parameter specifies the socket descriptors to be 
examined for readability. If zero is passed, no sockets will 
be examined. On output, readmap describes all readable 
sockets. 
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writemap 
(input/output) 


exceptionmap 
(input/output) 


timeout 


result 


A bit map indexed with NetIPC socket descriptors. On 
input, this parameter specifies the socket descriptors to be 
examined for writeability. If zero is passed, no sockets will 
be examined. On output, wri temap describes all writeable 
sockets. 

A bit map indexed with NetIPC socket descriptors. On 
input, this parameter specifies the socket descriptors to be 
examined for exceptions. If zero is passed, no sockets will 
be examined. On output, except ionmap describes all of 
the sockets that are exceptions. 

The number of tenths of seconds the calling process will 
wait for some event to occur which would cause 
ipcselect ()’s report to change. This timeout is put into 
effect only when none of the sockets referenced can 
immediately satisfy the select criteria (i.e., none are 
readable, writeable or exceptional). Valid values are zero, 

-1, or any positive integer. If timeout is set to zero, the call 
will not return until some event occurs. NOTE: Do not set 
t imeout to -1 if no bits are set in any of the bit maps as 
i psel ect () will block indefinitely. 

The error code returned; zero or NSRNOERROR if no error. 


Description 

i pcsel ect () permits a process to detect, and/or wait for, the occurrence of any of 
several events across any of several sockets. Compared to the telephone system, 
invoking i pcsel ect () is analogous to performing powerful “switchboard-like” 
operations because it enables a process to act as a “switchboard operator” by 
monitoring the sockets, or “telephones,” that it owns. A process should call 
i pcsel ect () with map elements set for descriptors that it owns. If a process 
attempts to perform a select on a closed or invalid descriptor, an error will be 
returned. Performing a select on a destination descriptor is meaningless. 
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i pcsel ect () reports three types of information: 

■ Whether any of the referenced VC sockets are readable. A VC socket is 
considered readable if it can immediately satisfy an i pcrecv () request for a 
number of bytes greater than or equal to its read threshold. Each VC socket has an 
associated read threshold which, when the socket is first created, is set to one byte. 
This value can be modified by calling i pccontrol () . (For more information on 
setting read thresholds, refer to “Synchronous and Asynchronous Socket Modes” in 
the “NetIPC Concepts” chapter.) Read selecting on call sockets has no meaning. 
Although doing so will not produce an error, this practice should be avoided. 

■ Whether any of the referenced call or VC sockets are writeable. A VC socket is 
considered writeable if it can immediately accommodate an i pc send () request 
that involves a number of bytes greater than or equal to the socket’s write 
threshold. Each VC socket has an associated write threshold which, when the 
socket is first created, is set to one byte. This value may be modified by calling 

i pccontrol (). (For more information on setting write thresholds, refer to 
“Synchronous and Asynchronous Socket Modes” in the “NetIPC Concepts” 
chapter.) 

■ Whether any of the referenced call or VC sockets are exceptional. A VC socket is 
considered exceptional if it has a problem associated with it (for example, the 
connection it references was aborted). A call socket is considered exceptional if it 
has a connection request queued on it or if it can no longer be supported by 
NetIPC. 

When a socket is shared (i.e., more than one process has a descriptor for the same 
socket), an ipcsend() call may return an NSR WOULD BLOCK error (code 56) even if 
a previous ipcselect() call indicated that the socket was writeable. For example, 
this would occur if another process (with a descriptor for the same socket) called 
i pcsend ( ) after the original process called i pcsel ect () and before it called 
ipcsend(). 

The following are examples of read selecting, write selecting, and exception selecting 
using i pcsel ect (). 
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Examples 

Detecting Connection Requests 

By setting bits in the except i onmap parameter, a process can determine if incoming 
connection requests are queued to certain call sockets. Consider the following 
example: Process A must determine whether certain call sockets have received 
connection requests. To do this, Process A calls i pcs el ect ()with the 
except ionmap map elements set to correspond to these sockets. Assuming that the 
time-out interval is long enough (set by the timeout parameter), ipcselect() will 
complete after at least one connection request has arrived and has been queued on 
one of the sockets specified in except ionmap. When the call completes, only those 
elements that correspond to sockets that have queued connection requests remain set; 
the other elements will have been cleared. 


Performing a Read Select 

By setting elements in the readmap parameter, a process can determine whether 
certain VC sockets are readable. Consider the following example: Process A must 
determine which of its VC sockets have data queued to them. To do this Process A 
performs a read select on those sockets by setting elements in the readmap parameter 
to correspond with the desired VC sockets. Upon completion of the call, only the 
elements that represent readable sockets will remain set; the other elements will have 
been cleared. Process A can call i pcsel ect () with a zero-length time-out to 
determine the status of a socket immediately, or with a non-zero timeout if it is willing 
to wait for some data to arrive. 


Performing a Write Select 

By setting bits in the wri temap parameter, a process can determine whether certain 
VC sockets are writeable. Consider the following example: Process A must determine 
which of its VC sockets can accommodate a new i pc send () request, and which of its 
call sockets can accommodate a new i pcconnect (); i pcsel ect () request. To do 
this, it can perform a write select on these sockets by setting elements in the 
wri temap parameter to correspond with the desired VC and call sockets. Upon 
completion of the call, only the elements that represent writeable sockets will remain 
set; the other elements will have been cleared. Process A can call i pcsel ect () with 
a zero-length timeout to determine the status of a socket immediately, or with a 
non-zero timeout if it is willing to wait before sending data on the connection. 
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Exception Selecting 

By setting bits in the except ionmap parameter, a process can determine whether 
certain connections have been aborted. VC sockets that reference aborted 
connections will always exception select as “true” (their elements will be set when the 
call completes). Exception selecting on VC sockets can also be useful when the 
connection associated with the socket is not fully established. Consider the following 
example: Process B has successfully created a VC socket descriptor via a call to 
i pcconnect (), but will not know whether or not the connection was established 
until it calls i pcrecv (). If Process B calls i pcrecv () before the connection is 
established, or before it becomes known that a connection cannot be established, it 
will block (if the VC socket is in synchronous mode), or return an NSR WOULD BLOCK 
error (if the VC socket is in asynchronous mode). Process B can avoid blocking or 
polling by performing an exception select on the new VC socket. The socket will 
select as true if the connection has been established (a call to i pcrecv () will be 
successful) or if there is a problem associated with it (a call to i pcrecv () will be 
unsuccessful.) 


Programming Considerations 

The following paragraphs explain how the readmap, wri temap , and except ionmap 
parameters are declared and manipulated in the C, Pascal, and FORTRAN 
programming languages. 


C Programming Language 

In the C programming language, the readmap, wri temap, and except ionmap 
parameters can be declared as integer arrays. For example: 

int read map [64]; 
int write map [64]; 
int exceptionmap [64]; 

This statement defines 2048 bits which can be set to correspond to specific call or VC 
socket descriptors. The following algorithm can be used to set bits in the array. (The 
socket descriptor is represented by the variable vcdesc.) 

read map [vcdesc/32] |= ((unsigned int) 0x80000000 » (vcdesc% 

32)); 
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The next algorithm can be used after an i pcsel ect () call completes to check 
whether or not a certain bit is set: 

readjnap [vcdesc/32] & ((unsigned int) 0x80000000 » (vcdesc% 

32)); 

Pascal Programming Language 

In Pascal, the readmap, wri temap and except ionmap parameters can be declared 
to be type map_type. This type is defined as follows: 

TYPE 

map type = packed array [0. .2047] of boolean; 

VAR 

read map : map type; 

To set a bit in any of these parameters to correspond to a specific call socket or VC 
socket, use the appropriate cal Idesc or vcdesc value as a subscript and assign the 
value TRUE. For example: 

read map [vcdesc] :=TRUE; 
wri temap [call desc] :=TRUE; 
exception map [vcdesc] : = TRUE; 

FORTRAN Programming Language 

In FORTRAN, the readmap , wri temap and except i onmap parameters may be 
declared as arrays of 64 32-bit integers (INTEGER*4). For example: 

INTEGER*4 read_map(64), write_map(64), exception_map(64) 

The first element of the array, readmap (1), contains map bits 0 through 31; the 
second element of the array, readmap(2), contains bits 32 through 63, etc. 

When setting a bit in the array, you must first determine whether your vcdesc or 
ca 1 Idesc parameter is greater than, less than, or equal to 31. If it is less than or 
equal to 31, you must set a bit in the first element of the array; if it is is greater than 
31, you must set a bit in the second element of the array, and so on. 
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The simplest way to set a bit in one of these parameters is to use the FORTRAN 
library function i bset (a, b) . The readmap , wri temap or except ionmap parameter 
is passed in the first argument (a) and the bit position you want to set is passed in the 
second argument (b). 

The i bset function assumes that bits are numbered from right to left, with the most 
significant bit considered to be bit 31 and least significant bit considered to be bit 0. 
NetIPC calls assume that bits are numbered in the opposite direction (i.e., the most 
significant bit is 0, the least significant bit is 31). Therefore, to set the proper bit 
using i bset, you must subtract the descriptor value from 31. 

In the following example, the vcdesc parameter is greater than 31 so the 
corresponding bit is set in the second element of the readmap parameter. Note that 
the vcdesc value must be subtracted from 63 so that the proper bit is set. This maps 
i bset’s bit numbering convention (which is from right to left) into NetIPCs (which is 
from left to right). 

read_map = ibset (read_map(2),(63-vcdesc)) 

In the next example, vcdesc is equal to 31 so the corresponding bit is set in the first 
element of the readmap parameter. Note that the vcdesc value must be subtracted 
from 31 so that the proper bit is set. Again, this maps i bset’s bit numbering 
convention (which is from right to left) into NetIPC’s (which is from left to right). 

read map= ibset (readmap(l),(31 -vcdesc)) 
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The following is a list of the type definitions and passing modes for the i pcsel ect () 
call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

sdbound 

ns_int_t *sdbound 

integer 
by reference 

integer*4 
by reference 

readmap 

int readmap[64] 

packed array of 
boolean 
by reference 

array of 
integer*4 
by reference 

writemap 

int writemap [64] 

packed array of 
boolean 
by reference 

array of 
integer*4 
by reference 

exceptionmap 

int 

exceptionmap[64] 

packed array of 
boolean 
by reference 

array of 
integer*4 
by reference 

timeout 

ns_int_t timeout 

integer 
by value 

integer*4 
by reference 

result 

ns_int_t *result 

integer 
by reference 

integer*4 
by reference 
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ipcsendO 

Sends data on a virtual circuit connection. 

Syntax 

ipcsend( vcdesc,data,dlen,f1ags,opt,result) 

Parameters 

vcdesc VC socket descriptor. Refers to the VC socket endpoint of 

the connection through which the data will be sent. A VC 
socket descriptor can be obtained by calling i pcconnect () 
and ipcrecvcn(). 

data A buffer that will hold the data to be sent, or a data vector 

describing where the data to be sent is located. Refer to 
“Data Parameter” for more information on the structure 
and use of this parameter. 

dlen If data is a data buffer, dlen is the length in bytes of the 

data in the buffer. If data is a data vector, dlen is the 
length in bytes of the data vector. 

fl ags Refer to “Data Parameter” for more information on the 

structure and use of this parameter. The following bits are 
defined for this call: 

• bi t 26 NSFMOREDATA (input). When this bit is set, 
TCP may delay sending data. Refer to the 
“Description” below for more information. 

• bit31 NSF_VECTORED (input). Indicates that the data 
parameter refers to a data vector and not to a data 
buffer. 
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opt 


An array of options and associated information. Refer to 
“NetIPC Common Parameters” for more information on the 
structure and use of this parameter. The following option is 
defined for this call: 

• optioncode = NS0_DATA_0FFSET (code 8), 

datalength = 2). A two-byte integer that indicates a 
byte offset from the beginning of the data buffer where 
the data to be sent actually begins. Only valid if the 
data parameter is a data buffer. 

result The error code returned; zero or NSR_N0_ERR0R if no error. 


Description 

The i pcsend () call is used to send data on an established connection. The data may 
be sent as a single contiguous buffer or as a scattered data vector. If the data is 
vectored, NetIPC will gather all the referenced data before sending it. For vectored 
writes, an i ovec structure contains the data vector. An i ovec structure can be 
defined in C as: 

struct iovec { 
char 

unsigned 

}; 

and the normal type for the data argument can be replaced by struct iovec *data. 
Each i ovec entry specifies the base address and length of an area in memory where 
the data should be placed. 

If the NSF MORE DATA bit (bit 26) of the fl ags parameter is set, the Transmission 
Control Protocol (TCP) may not immediately transmit the data indicated by the data 
parameter. Instead, it may wait until it has received an amount of data that can be 
transmitted with the greatest efficiency. Several transmissions of small amounts of 
data consume more resources than one large transmission. If NSF_MORE_DATA is not 
set, TCP will attempt to transmit the data immediately, regardless of efficiency 
considerations. If your process will be sending large amounts of data, HP 
recommends that you set NSF_MORE_DATA. If NSF_MORE_DATA is set and you submit 
only a small amount of data (less than a few hundred bytes), then TCP may hold onto 
the data for a considerable period of time before transmitting it. 


*iov_base; 
iov_len; 
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Synchronous vs. Asynchronous I/O 

i pcsend( ) functions differently depending on whether the VC socket referenced is 
in synchronous or asynchronous mode. The following paragraphs describe these 
differences: 

■ Synchronous I/O. Send requests issued against VC sockets in synchronous mode 
may block, i pcsend () will block if it can not immediately obtain the buffer space 
needed to accommodate the data. The call will resume after the required buffer 
space becomes available, or if the synchronous timer expires. Timeouts usually 
occur when the process on the receiving end of the connection stops receiving the 
data sent to it. (The length of the synchronous time-out interval can be adjusted via 
i pccontrol (). Refer to the discussion of this call for more information.) 

■ Asynchronous I/O. Send requests issued against sockets in asynchronous mode will 
never block. If the buffer space needed to accommodate the data is not 
immediately available, a NSR_W0ULD_BL0CK error (code 56) is returned. After 
receiving this error, the process can try the call again later, or determine when the 
socket is writeable by calling i pcsel ect (). (Refer to the discussion of 

i pcs el ect () for more information on writeable sockets.) 

For a detailed discussion of synchronous and asynchronous I/O, refer to “Synchronous 
and Asynchronous Socket Modes” in the “NetIPC Concepts” chapter. 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the i pcsend() 
call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

vcdesc 

ns_int_t vcdesc 

integer 
by value 

integer*4 
by value 

data 

char *data 

packed array of 
characters 
by reference 

array of 
characters 
by reference 

dlen 

ns_int_t dlen 

integer 
by value 

integer*4 
by value 

flags 

ns_int_t *flags 

boolean array 
by reference 

integer *4 
by reference 

opt 

short int opt[] 

array of bytes 
by reference 

array of integers 
by reference 

result 

ns_int_t * result 

integer 
by reference 

integer*4 
by reference 
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ipcsetnodenameO 

Sets the NetIPC node name of the host CPU. 


Syntax 


j pcsetnodename() (nodename,name!en,result) 


Parameters 

nodename The ASCII-coded name that is assigned to this host. 

Default: You may omit the organization or the organization 
and domain and this field will default to the organization 
and/or domain previously set by setnodename. 

name 1 en The length in bytes of the nodename parameter. 

resu 11 The error code returned; zero or NSR_N0_ERR0R if no error. 

Description 

The i pcsetnodename( ) call sets the NetIPC node name of the host processor to the 
node name value. 

Super-user capability is required to use this call. 
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ipcshutdownO 

Releases a descriptor. 


Syntax 


ipcshutdown( descriptor,flags , opt,result) 


Parameters 

descriptor 


flags 


opt 


result 


The descriptor to be released. May be a call socket 
descriptor, VC socket descriptor, or destination descriptor. 

Must be 0 or NSF_GRACEFUL_RELEASE. If this flag is set, 
the underlying network protocol will continue to transmit 
data after the calling process exits. (Refer to “Flags 
Parameter” for more information on the structure of this 
parameter.) 

Refer to “Opt Parameter” for more information on the 
structure and use of this parameter. No options are 
defined for this call. May be 0 or a pointer to an empty 
NetIPC option buffer. 

The error code returned; zero or NSRNOERROR if no error. 


Description 

The ipcshutdown() call is used to release a descriptor. The descriptor referenced 
may be a call socket descriptor, VC socket descriptor, or destination descriptor. How 
i pcshutdown () functions depends on which type of descriptor is being used. If the 
descriptor is a: 
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■ Call socket descriptor, the descriptor is released along with any names associated 
with it. The process that released the call socket descriptor may no longer use it, 
and all connection requests queued to that descriptor are aborted. The call socket 
referenced by the descriptor is destroyed along with the descriptor and names only 
if the descriptor being released is the last descriptor for that socket. If another 
process, or processes, have a descriptor for the same socket, these duplicate 
descriptors are not affected. Since system resources are used when a call socket is 
created, you may want to release your call socket descriptors when they are no 
longer needed. A call socket descriptor is needed as long as a process is expecting 
to receive a connection request on that socket. After the connection request is 
received via i pcrecvcn (), and as long as no other connection requests are 
expected for that call socket descriptor, the descriptor can be released. Similarly, a 
process that requests a connection can release its call socket descriptors any time 
after its call to i pcconnect (), as long as it is not expecting to receive a connection 
request on that descriptor. Using i pcshutdown () to release a call socket 
descriptor does not affect any VC sockets. 

■ Destination descriptor, the descriptor is released along with any names associated 
with it in the local socket registry. The process that released the destination 
descriptor may no longer use it. The addressing information stored in conjunction 
with the descriptor is destroyed along with the descriptor only if the descriptor 
being released is the sole descriptor for that information. If another process, or 
processes, have a descriptor for the same information, these duplicate descriptors, 
and any names associated with the descriptors, are not affected. Because 
destination descriptors also require system resources, you may want to release them 
when they are no longer needed. 

■ VC socket descriptor, the VC socket descriptor is released and the referenced 
connection is aborted and is no longer available for sending or receiving data. The 
VC socket descriptor is released along with the descriptor only if the descriptor 
being released is the last descriptor for that socket. If another process, or 
processes, have a descriptor for the same VC socket, these duplicate descriptors are 
not affected. Because i pcshutdown () takes effect very quickly, all of the data that 
is in transit on the connection, including any data that has already been queued on 
the destination VC socket, may be destroyed when the connection is shut down. 
Shutting down a VC socket does not affect any call sockets. 

All of the data that is in transit on a VC socket, including any data that has already 
been queued on the destination VC socket, may be destroyed when the connection is 
shut down unless the NSF_GRACEFUL_RELEASE flag is set. If a process sends 
important data to its peer process just prior to shutting that process down, it is 
recommended that the calling process receive a confirmation from the peer process 
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before calling ipcshutdown or exiting, or use the NSF_GRACEFUL_RELEASE flag to 
ensure that the data was received. 

For more information on ipcshutdown(), refer to “Shutting Down a Connection” in 
the “NetIPC Concepts” chapter. 


Programming Considerations 

The following is a list of the type definitions and passing modes for the 
ipcshutdown() call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

descriptor 

ns_int_t 

descriptor 

integer 
by value 

integer*4 
by value 

flags 

ns_int_t *flags 

boolean array 
by reference 

integer*4 
by reference 

opt 

short int opt[J 

array of bytes 
by reference 

array of integers 
by reference 

result 

ns_int_t *result 

integer 
by reference 

integer*4 
by reference 


Cross-System Considerations 

Socket Shut Down - The shutdown procedure for the HP 1000, HP 9000 and HP 
3000 processes is identical except for shared sockets on HP 9000 and the “graceful 
release” flag on the HP 3000 and 9000. Shared sockets are destroyed only when the 
descriptor being released is the sole descriptor for that socket. Therefore, the HP 
9000 process may take longer to close the connection than expected. If the graceful 
release flag is set on the HP 3000, the HP 9000 will respond as though it were a 
normal shutdown request. 
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optoverheadO 

Returns the number of bytes needed for the opt parameter in a subsequent NetIPC 
call, not including the data portion of the parameter. 


Syntax 


optlength = optoverhead( eventua1entries , resu 71) 


Parameters 

opt 7 ength The number of bytes required for the opt parameter, not 

including the data portion of the parameter. 

eventua 1 entri es The number of option entries that will be placed in the opt 

parameter. 

result The error code returned; zero or NSR_N0_ERR0R if no error. 

Description 

The optoverhead() call returns the number of bytes needed for the opt parameter, 
excluding the data area. 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the 
optoverhead () call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

optlength 

short int 
(returned value) 

intl6* 

(returned value) 

integer 

(returned value) 

eventualentries 

short int 
(returned value) 

intl6* 
by value 

integer 
by value 

error 

short int *error 

intl6* 

by reference 

integer 
by reference 


*intl6 is a user-defined Pascal type for a 16-bit integer. 
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readoptO 

Obtains the option code and argument data associated with an opt parameter 
argument. 


Syntax 


re adopt( opt , argnum,optiopcode,datalength.data , resu11 ) 


Parameters 

opt 

argnum 

optioncode 

dat a7 ength 
(input/output) 


data 

result 


The opt parameter to be read. Refer to “NetIPC Common 
Parameters” for information on the structure and use of this 
parameter. 

The number of the argument to be obtained. The first 
argument is number zero. 

The option code or constant definition (C programs only) 
associated with the argument. These codes are described in 
each NetIPC call opt parameter description. 

The length of the array into which the argument should be 
read. If the array is not large enough to accommodate the 
argument data, an error will be returned. On output, this 
parameter contains the length of the data actually read. 

(The length of the data associated with a particular option 
code is provided in each NetIPC call opt parameter 
description.) 

An array which will contain the data read from the argument. 
The error code returned; zero or NSRNOERROR if no error. 
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Programming Considerations 

The following is a list of the type definitions and passing modes for the readopt () 
call parameters in C, Pascal, and FORTRAN. 


Parameter 

C 

PASCAL 

FORTRAN 

opt 

short int opt[] 

array of bytes 
by reference 

array of integers 
by reference 

argnum 

short int argnum 

intl6* 
by value 

integer 
by value 

optioncode 

short int 
*optioncode 

intl6* 

by reference 

integer 
by reference 

datalength 

short int 
*datalength 

intl6* 

by reference 

integer 
by reference 

data 

short int datafj 

array of intl6* 
by reference 

array of integers 
by reference 

error 

short int *error 

intl6* 

by reference 

integer 
by reference 


*int!6 is a user-defined Pascal type for a 16-bit integer. 
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A 


Sample NetIPC Programs 


The following are NetIPC program examples. This appendix is organized in two 
sections: HP 9000 to HP 9000 examples and cross-system NetIPC examples. 
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HP 9000 to HP 9000 Examples 

The following program examples were developed for HP 9000 to HP 9000 
communication: 

■ Example 1: Server Program in C. 

■ Example 2: Client Program in C. 

■ Example 3: Server Program in FORTRAN. 

■ Example 4: Client Program in FORTRAN. 

These programs are included in /usr/netdemo/nsi pc. 
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Cross-System NetIPC Examples 

The following programs were tested with equivalent client/server programs running on 
the HP 1000 and HP 3000 (MPE-V and MPE/iX). HP 1000 and HP 3000 NetIPC 
program examples are contained in the NetIPC documentation provided for those 
systems. 

■ Example 5: Cross-System Server in C. 

■ Example 6: Cross-System Client in C. 

■ Example 7: Cross-System Server in FORTRAN. 

■ Example 8: Cross-System Client in FORTRAN. 

■ Example 9: Cross-System Server in PASCAL. 

■ Example 10: Cross-System Client in PASCAL. 
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Make File for Sample Programs 


!/bin/sh 


# 


Make file for building the sample NetIPC tests. 

# 


# 

# 

# 


Compile NetIPC sample programs(2) in C. 

all : req_c serv_c req_f serv_f 

serv_c : serv.c 

cc -o serv_c serv.c - Insipc 

req_c : req.c 

cc -o req_c req.c - Insipc 

serv_f : serv.f 

fc -o serv_f serv.f - lnsipc 

req_f : reg.f 

fc -o req_f req.f - lnsipc 
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Example 1: Server in C 

/* 

* This is a server program which executes in background on an 

* 840 machine. It creates a call socket and names it ABCDEFGH . 

* The server waits indefinitely for a connection request. After 

* a request is received and connection established by the 

* ipcrecvcn() call, the server forks a child to handle all data 

* exchange with the requester. The server then loops back to wait 

* for new connection requests. 

* 

* The child receives and logs all messages sent by the requester. 

* When a shut down message is received, it sends the shut down 

* message back to the requester. The next ipcrecv() call will 

* return a 64 error, signifying that the requester has disconnected. 

* The child process then calls ipcshutdown() and terminates. 

* 

* Although the program executes in background, you do not have to 

* invoke it with a & . It automatically puts itself in the background. 

* This server program is the peer program to the requester 

* program written in C (Example 2) and FORTRAN (Example 4). 

V 

#include <stdio.h> 

#include <sys/types.h> 
finclude <sys/ns_ipc.h> 

#include <sys/time.h> 

#include <sys/fcnt1.h> 
linclude <signal.h> 

#include <errno.h> 
finclude <sys/uio.h> 

#include <string.h> 


fdefine MSG_SIZE 20 

ns_int_t result; 
short opt [100]; 
short opterr; 
ns_int_t flags; 
char logbuf[100]; 

char *sd_msg = I want to shut down. ; 

char *logfile = ./ipc.log ; 
int logf; 

main (argc, argv) 
int argc; 
char **argv; 

{ 

ns_int_t vc_desc, call__desc; 
char *socketname; 

short short_timeout; 
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init_logging (); 

/* forks in order to get into the background and detaches 
* process from tty 

*/ 

if (fork()) 
exit (0); 
setpgrp (); 


/* ignore signals */ 
signal(SIGCLD, SIG_IGN); 


/* create call socket */ 
flags = 0; 

initopt (opt, 0, &opterr); /* initialize opt to zero opt */ 
ipccreate (NS_CALL, NSP_TCP, &flags, opt, &call_desc, Sresult); 
sprintf (logbuf, ipccreate: %d\n , result); 
log (logbuf); 

if (result) goto fatal_error; 


/* name the call socket */ 
socketname* ABCDEFGH ; 

ipcname (call_desc, socketname, 8, &result); 

sprintf (logbuf, ipcname %s: %d\n , socketname, result); 

log (logbuf); 

if (result) goto fatal_error; 


/* set call socket timeout to infinite, then wait for 
connection requests */ 

flags = 0; 
short_timeout = 0; 

ipccontrol (call_desc, NSC_TIME0UT_RESET, &short_timeout, 2, 0, 0, 
Sflags, &result); 

sprintf (logbuf, ipccontrol NSC_TIMEOUT_RESET: %d\n , result); 
log (logbuf); 

if (result) goto fatal_error; 


while (Jresult) 

{ 

flags = 0; 

ipcrecvcn (call_desc, &vc_desc, &flags, opt, &result); 
sprintf (logbuf, ipcrecvcn: %d\n , result); 
log (logbuf); 

if (result) goto fatal_error; 


A-6 Sample NetIPC Programs 



/* fork a child and pass it the newly established 
connection */ 

if (!fork()) 

{ /* child */ 

rec_data (vc desc); 

if (!result T| result == NSR_REMOTE_ABORT) 
exit (0); 
else 

exit (result); 

} 

/* parent */ 
flags = 0; 

ipcshutdown (vc_desc, &flags, opt, Sresult); 


fatal_error: sprintf (logbuf, fatal_error: %d\n , result); 
log (logbuf); 
exit (result); 

} 

rec_data (vc_desc) 
ns_int t vc_desc; 

{ 


char buf[MSG_SIZE + 1]; 
ns_int_t msg_len; 
int shut_down = 0; 

for(;;) . 

{ 

flags = 0; 
msgjen = MSG_SIZE; 

ipcrecv (vc_desc, buf, &msg_len, &flags, opt, &result); 
sprintf (logbuf, ipcrecv: %d\n , result); 
log (logbuf); 

if (result) goto return_error; 

if(!strncmp(buf, sd_msg, MSG_SIZE)) 

{ 

sprintf(logbuf, Shutdown msg received\n ); 

log(logbuf); 

flags = 0; 

msg_len = MSG_SIZE; 

ipcsend (vc_desc, buf, msg_len, &flags, opt, Sresult); 
sprintf (logbuf, ipcsend: %d\n , result); 
log (logbuf); 

} 

else 

{ 

buf[MSG_SIZE] = (char) 0; 

sprintf(logbuf. Received: %s\n , buf); 

log(logbuf); 
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} 

> 

return_error: flags = 0; 

ipcshutdown (vc_desc, &flags, opt, Sresult); 
sprintf (logbuf, ipcshutdown: %d\n , result); 
log (logbuf); 
return (result); 

} 

init_logging() 

{ 

int flags; 

flags = 0_CREAT | 0_WR0NLY | 0_APPEND; 
logf = open (logfile, flags, 0777); 
if (logf < 0) { 

printf ("Couldn't open log file\n"); 
exit (-1); 

} 

log ("ipcserver starts\n"); 

} 


log (buf) 
char *buf; 

{ 

int pid = getpid(); 
char *ctime(), *time_str; 
struct tirtieval tv; 
struct timezone tz; 
char time [25]; 
char local_buffer[160] ; 

gettimeofday (&tv, &tz); 
time_str = ctime (&(tv.tv_sec)); 
bcopy (time_str, time, 24); 
time[24] = 0; 

sprintf (local_buffer, %s: {%d}: %s\n , time, pid, buf); 
write (logf, local_buffer, strlen(local_buffer)); 

> 


bcopy (from_str, to_str, len) 
char *from_str; 
char *to_str; 
int len; 

{ 

while (len ) 

*to_str++ = *from_str++; 

} 
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Example 2: Client in C 

/* This program initiates a connection to a remote socket ABCDEFGH , 

* then sends some messages to the server. When this program is ready 

* to quit, it will send a shut-down message to the server. After 

* the server has acknowledged the shut-down message, the shut-down 

* operation is performed. 

*/ 

#include <stdio.h> 

#include <sys/ns_ipc.h> 

#include <string.h> 

main (argc, argv) 
int argc; 
char **argv; 

{ 

ns_int_t vc_desc, dest_desc; 
ns_int_t protocol, sock_kind; 
ns_int_t result; 
short opt[100] ; 
short opterr; 
ns_int_t flags; 
char *progname; 
char *nodename; 
char *socketname; 
char buf[64]; 

static char shut_down[ ] = I want to shut down. ; 

static char msg[ ] = Message from request ; 

ns_int_t readlen; 
short timeout, datalen; 

/* the first argument after the program name indicates the 
node on which ABCDEFGH resides */ 

progname = *argv++; 
nodename = *argv; 


/* obtain destination descriptor to socket ABCDEFGH on 
the remote node that is passed as an argument to the 
program */ 

socketname= ABCDEFGH ; 
flags = 0; 

ipclookup (socketname, 8, nodename, strlen(nodename), Sflags, 
&dest_desc, Sprotocol, &sock_kind, Sresult); 
printf ("{%s} ipclookup: %d\n", progname, result); 
if (result) goto fatal_error; 


/* initialize opt structure */ 
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initopt (opt, 0, Sopterr); /* initialize opt to zero opt */ 
ipcconnect (-1, dest_desc, &flags, opt, &vc_desc, &result); 
printf ("{%s} ipcconnect: %d\n", progname, result); 
if (result) goto fatal_error; 


/* release destination descriptor since it's not needed 
any more */ 

ipcshutdown (dest_desc, Sflags, opt, &result); 
printf (”{%s} ipcshutdown: %d\n", progname, result); 
if (result) goto fatal_error; 

/* confirm connection */ 

flags = 0; 

ipcrecv (vc_desc, buf, Sreadlen, &flags, opt, Sresult); 
printf ("{%s} ipcrecv connection: %d\n", progname, result); 
if (result) goto fatal_error; 

flags = 0; 

printf("{%s} Sending requester's message\n", progname); 
ipcsend (vc_desc, msg, 20, Sflags, opt, Sresult); 
if (result) goto fatal_error; 

flags = 0; 

printf("{%s} Sending shutdown message\n", progname); 
ipcsend (vc_desc, shut_down, 20, &flags, opt, &result); 
if (result) goto fatal_error; 

flags = NSF_DATA_WAIT; 
readlen = 20; 

printf("{%s} Waiting to receive shutdown acknowledgement\n", progname); 
ipcrecv (vc_desc, buf, &readlen, &flags, opt, Sresult); 
printf ("{%s} ipcrecv: %s\n”, progname, buf); 
if (result) goto fatal_error; 


if (strncmp (buf, shut_down, 20)) 

{ 

printf ("strcmp failed %s, %s\n", buf, shut_down); 
goto return_error; 

> 

flags = 0; 

ipcshutdown (vc_desc, &flags, opt, &result); 
printf (”{%s) ipcshutdown: %d\n", progname, result); 

return_error: exit(0); 

fatal_error: printf (”{%s} fatal error: %d\n”, progname, result); 
exit (result); 

} 


A-10 Sample NetIPC Programs 



Example 3: Server in FORTRAN 

PROGRAM serf 


C 

C NAME: serf 

C SOURCE: 91790-18237 

C RELOC: 91790-16237 

C PGMR: ZL 

C Modified by KC for the 840 

C This program is the peer process to requester. It uses sockets in 

C synchronous mode to establish a connection and receive a message 

C from requester. 

C Since FORTRAN values are passed by value by default, the ALIAS 

C statements below are used to indicate which values of the IPC calls 

C should be passed by reference instead. 

$ALIAS ipcconect (%val,%val,%ref,%ref,%ref,%ref) 

$ALIAS ipccontrol (%val,%val,%ref,%val,%ref,%ref,%ref,%ref) 

$ALIAS ipccreate (%val,%val,%ref,%ref,%ref,%ref) 

$ALIAS ipcdest (%va1,%ref,%va1,%va1,%ref,%va1,%ref,%ref,%ref,%ref) 

$ALIAS ipclookup (%ref,%val,%ref,%val,%ref,%ref,%ref,%ref,%ref) 

$ALIAS ipcname (%val,%ref,%val,%ref) 

$ALIAS ipcnamerase (%ref,%val,%ref) 

$ALIAS ipcrecv (%val,%ref,%ref,%ref,%ref,%ref) 

$ALIAS ipcrecvcn (%val,%ref,%ref,%ref,%ref) 

$ALIAS ipcselect (%ref,%ref,%ref,%ref,%val,%ref) 

$ALIAS ipcsend (%val,%ref,%val,%ref,%ref,%ref) 

$ALIAS ipcshutdown (%val,%ref,%ref,%ref) 

$ALIAS addopt (%ref,%val,%val,%val,%ref,%ref) 

$ALIAS initopt (%ref,%val,%ref) 

$ALIAS readopt (%ref,%val,%ref,%ref,%ref,%ref) 

$ALIAS signal (%val,%val) 

PARAMETER (SIGCLD=1, SIG_IGN=1, NSC_TIME0UT_RESET=3) 

CHARACTER*20 receive_buffer, shut_down_message 
CHARACTER*8 socket_name 

INTEGER*2 opt ion(2), result, timeout 

C INTEGER SIGCLD, SIG_IGN, request, NSC_TIMEOUT_RESET, fork 
INTEGER request, fork 

INTEGER socket_kind, protocol_kind, call_socket_descriptor, 
>error_return, name_length, VC_socket_descriptor, 
>message_buffer_length, flags_array 

DATA shut_down_message/'I want to shut down.'/ 

C Fork Process to get into background and detach from controlling tty 
C and ignore SIGCLD (dealth of child process). 
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if (fork() .NE. 0) STOP 
call setpgrpO 

call signal(SIGCLD, SIG_IGN) 

The INITOPT call initializes the option parameter used by the 
IPCCREATE, IPCRECVCN, IPCRECV and IPCSHUTDOVN calls. By setting 
the opt_num_arguments parameter to zero, the option parameter is 
initialized to contain zero entries. (An example of adding entrie 
to an option parameter is included in the discussion of ADDOPT in 
this section. 

opt_num_arguments = 0 

CALL INITOPT(option,opt_num_arguments,result) 
here = 1 

IF(result.NE.O) GO TO 99 

socket_kind is set to 3 and protocol_kind is set to 4 to 
specify a call socket and the TCP protocol for the following 
IPCCREATE call. 

socket_kind = 3 
protocol_kind = 4 

The flags parameter is not used in this program, so flags_array 
is made a double integer and assigned the value zero to ensure 
that all the bits are clear. 

flags_array = 0 

A call socket is created by calling IPCCREATE. The value returned 
in the call_socket_descriptor parameter will be used in the following 
IPCNAME call. 

CALL IPCCREATE(socket_kind,protocol_kind,f1ags_array,option, 

>ca1l_socket_descriptor,error_return) 

here = 2 

IF(error_return.NE.O) GO TO 99 
flags_array = 0 

C IPCNAME is called to assign a name to the newly-created call 

C socket. This name is known to the requester. 

socket_name = 'ABCDEFGH' 
name_length = 8 

CALL IPCNAME(ca1l_socket_descriptor,socket_name,name_length, 
>error_return) 

here = 3 

IF(error_return.NE.O) GO TO 99 
C Set call VC socket to infinite. 
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flags_array = 0 
timeout = 0 

request = NSC_TIMEOUT_RE$ET 

CALL IPCCONTROL(call_socket_descriptor, request, timeout, 

>2, 0, 0, flags_array, error_return) 

here = 4 

IF (error_return .NE. 0) 60 TO 99 
flags_array = 0 

C The following IPCRECVCN call will receive the connection request 

C sent by requester and return a VC socket descriptor. Once this call 

C has completed successfully, you may optionally release the call 
C socket descriptor by calling IPCSHUTDOWN in order to return resources 

C to the system. Doing so will not affect the newly-created 

C VC socket descriptor. 

CALL IPCRECVCN(ca1l_socket_descriptor,VC_socket_descriptor, 

>f1ags_array.option,error_ret urn) 

here = 5 

IF(error_return.NE.O) GO TO 99 

C IPCRECV is called to receive a message from requester. 

10 flags_array = 0 

message_buffer_length = 20 

CALL IPCRECV(VC_socket_descriptor,receive_buffer, 

>message_buffer_length,flags_array,option,error_return) 

C If error code 64 is received, requester has shut down the connection 

C at its node. The error processing code at statement 99 

C will call IPCSHUTDOWN to shut down the server's VC socket descriptor. 

here = 6 

IF(error_return.NE.O) GO TO 99 

C The receive buffer is compared to the shut down message. 

C If the shut down message is received, server sends a shut 
C down message back to requester so that requester will know that its 
C data has been received. 

IF(receive_buffer .EQ. shut_down_message) THEN 
flags_array = 0 

CALL IPCSEND(VC_socket_descriptor,shut_down_message, 

> message_buffer_length,f1ags_array,option,error jreturn) 

here = 7 

IF(error_return.NE.O) THEN 
GO TO 99 
ELSE 

GO TO 10 
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ENOIF 

ELSE 

C If the shut down message was not received, ipcl will simply rece 
C the data and print it. It then returns to the previous IPCRECV ca 

C to receive subsequent data until either the shut down message 

C is received or an error occurs. 

C WRITE(6,'(5A4)')(receive_buffer(index),index = 1,5) 

WRITE(6,*) receive_buffer 
GO TO 10 
ENDIF 

99 IF(error_return.EQ.64) THEN 

flags_array = 0 

CALL IPCSHUTDOWN (VC_socket_descriptor,flags_array,option, 

> error_return) 

IF(error_return.NE.O) GO TO 99 
ELSE 

WRITE(6,'("error_return error code : _”,I4)') error_return 
WRITE(6,'("result error code: _",I4)') result 
WRITE(6,’("Program server at location: ”,I4)') here 
ENDIF 

100 STOP 
END 
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Example 4: Client in FORTRAN 

PROGRAM reqf (location) 


C 

C NAME: reqf 

C SOURCE: 91790-18238 

C RELOC: 91790-16238 

C PGMR: ZL 

C Modified by KC to run on a 840 

C 

C This program is the peer process to server. It uses sockets 

C in synchronous mode and sends a message to server. 


$ALIAS ipcconnect (%val,%val,%ref,%ref,%ref,%ref) 

$ALIAS ipccontrol (%val,%val,%ref,%val,%ref,%ref,%ref,%ref) 

$ALIAS ipccreate (%val,%val,%ref,%ref,%ref,%ref) 

$ALIAS ipcdest (%va1,%ref,%va1,%va1 f %ref,%va1,%ref f %ref r %ref,%ref) 
$ALIAS ipc lookup (%ref,%val,%ref,%val,%ref,%ref,%ref,%ref,%ref) 

$ALIAS ipcname (%val,%ref,%val,%ref) 

$ALIAS ipcnamerase (%ref,%val,%ref) 

$ALIAS ipcrecv (%val,%ref,%ref,%ref,%ref,%ref) 

$ALIAS ipcrecvcn (%val r %ref,%ref,%ref,%ref) 

$ALIAS ipcselect (%ref,%ref,%ref,%ref,%val,%ref) 

$ALIAS ipcsend (%val,%ref,%val,%ref,%ref,%ref) 

$ALIAS ipcshutdown (%val.%ref,%ref,%ref) 

$ALIAS addopt (%ref,%val,%val,%val,%ref,%ref) 

$ALIAS initopt (%ref,%val,%ref) 

$ALIAS readopt (%ref,%val,%ref,%ref,%ref,%ref) 

PARAMETER (NSF_DATA_WAIT = 4000B) 

CHARACTER*20 receive_buffer, send_buffer, shut_down_message 

CHARACTER*50 location 

CHARACTER*8 socket_name 

CHARACTER*20 data_buffer 

INTEGER*2 option(2), result, num_arg, 

>opt_num_arguments, counter 

INTEGER*4 socket_kind, protocol_kind, call_socket_descriptor, 
>error_return, name_length, VC_socket_descriptor, 
>message_buffer_length, location_length, data_length, 
>path_report_descriptor, protocol_returned, flags_array 

DATA send_buffer/'Here is the message.'/ 

DATA shut_down_message/'I want to shut down.'/ 

C INITOPT is called to initialize the option parameter used in the 

C IPCCREATE, IPCL00KUP, IPCCONNECT, IPCRECV, IPCSEND and 

C IPCSHUTDOWN calls. By setting opt_num_arguments to zero, the 
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C option parameter is initialized to contain zero entries. 

C (An example of adding options to an option parameter is included 
C in the discussion of ADDOPT in this section. 


DO i = 1,50 

IF (location(i:i).EQ." ) THEN 
location length = i - 1 
GO TO 125 
ENDIF 

END DO 

125 CONTINUE 

IF (location_length .EQ. 0) THEN 
WRITE(6, *) ’reqf : usage reqf nodename' 

STOP 
ENDIF 

opt_num_arguments = 0 

CALL INITOPT(option,opt_num_arguments,result) 
here = 1 

IF(result.NE.O) GO TO 99 

socket_kind is set to 3 and protocol_kind is set to 4 to specify 
a call socket and the TCP protocol for the following IPCCREATE 
call. 

socket_kind = 3 
protocol_kind = 4 

The flags_array parameter is not used in this program so flags_array 
is made a double integer and assigned the value zero to ensure tha 
all the bits are clear. 

flags_array = 0 

A call socket is created by calling IPCCREATE. The value returned 
in the call socket_descriptor parameter will be used in the following 
IPCCONNECT call. 

CALL IPCCREATE(socket_kind,protocol_kind,flags_array,option, 

>ca1l_socket_descriptor,error_return) 

here = 2 

IF(error_return.NE.O) GO TO 99 

The location parameter indicates the node name of the node where 
ipc2 resides and location_length indicates the length of this 
name in bytes. Note that the organization and domain are defaulted. 

socket_name = ’ABCDEFGH' 
name_length = 8 

IPCL00KUP searches the socket registry at nodel for server's 
socket name. This call returns a path_report_descriptor that is 
used in the following IPCCONNECT call to request a connection 
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with server. Because it is possible for IPCLOOKUP to search for 
the socket name before server places it in its node's socket 
registry, server will try to look up the name several times before 
aborting. 

counter = 0 
flags_array = 0 

CALL IPCLOOKUP(socket_name,name_length,location,location_length, 

>flags_array,path_report_descriptor,protocol_returned,socket_kind, 
>error_return) 

counter = counter + l 
here = 4 

IF (error_return.EQ.O) GO TO 28 
IF (error_return.NE.37) GO TO 99 
IF (counter.LE.10) THEN 
GO TO 21 

ELSE 

GO TO 99 

ENDIF 

flags_array = 0 

The call_socket_descriptor returned by IPCCREATE and the 
path_report_descriptor returned by IPCLOOKUP are used in 
IPCCONNECT to request a connection with server. The 
VC_socket_descriptor returned by IPCCONNECT is used in subsequent 
calls to reference the connection. Once this call has completed 
successfully, you may optionally release the call socket descriptor 
by calling IPCSHUTDOWN in order to return resources to the system. 
Doing so will not affect the newly-created VC socket descriptor. 


28 CALL IPCCONNECT(ca1l_socket_descriptor,path_report_descriptor, 

>flags_array,opt ion,VC_socket_descriptor,error_return) 

here = 5 

IF(error_return.NE.O) GO TO 99 

flags_array = 0 
data_length = 20 

C IPCRECV is called to determine if the connection has been 
C established. 

CALL IPCRECV(VC_socket_descriptor,data_buffer,data_length, 

>flags_array,opt ion,error_return) 

here = 6 

IF(error_return.NE.O) GO TO 99 

flags_array = 0 
message_buffer_length = 20 
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C Data is sent to server on the newly established connection. 

CALL IPCSEND(VC_socket_descriptor,send_buffer, 

>message_buffer_1ength,flags_array,option f error_return) 

here = 7 

IF(error_return.NE.O) 60 TO 99 
flags_array = 0 

C After the data is sent, requester initiates the shut down dialogue 

C by sending a shut down message to server. 

CALL IPCSEND(VC_socket_descriptor,shut_down_message, 

>message_buffer_length,f1ags_array,option,error jreturn) 

here = 8 

IF(error_return.NE.O) 60 TO 99 

After it receives the shut down message, server will send its 
own shut down message to requester. IPCRECV is called to receive 
this data. 

flags_array = 0 

CALL IPCRECV(VC_socket_descriptor,receive_buffer, 

>message_buffer_length, flags_array,opt ion,error jreturn) 

here = 9 

IF(error_return.NE.O) 60 TO 99 

If the receive_buffer contains the shut down message, requester will 
call IPCSHUTDOWN to shut down its VC socket descriptor and termina 
the connection. 

IF(receive_buffer.EQ.shut_down_message) THEN 
flags_array = 0 

CALL IPCSHUTDOWN (VC_socket_descriptor,flags_array,opt ion, 

>error jreturn) 

here =10 

IF(error_return.NE.O) 60 TO 99 
60 TO 100 

Since the only data requester receives from server is a shut down messag 
it should never branch to the following ELSE statement. If this 
process were the recipient of several IPCSEND calls, it should 
call IPCRECV again. 

ELSE 

C WRITE(6,'(10A2)')(receive_buffer(index),index=l,10) 

WRITE(6, *) receiver_buffer 
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GO TO 30 


ENDIF 

99 WRITE (6, '("result error code: - ,14)') result 

WRITE (6, '( error_return error code: _",I4)') error_return 
WRITE (6, '("Program requester at location: _",I4)') here 

100 STOP 
END 
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Example 5: Cross-System Server in C 

/* NETIPC C-SERVER EXAMPLE 
★ 

* This program similates a local database system which waits 

* for remote information requests. It will looks for a reqular 

* 80 column text file called 'datafile' for information, 'datafile' 

* must conform with the following format: The first 20 chars 

* store a person's name, and the rest of the line stores the 

* information of that person. 

* 

* The program creates a call socket at TCP port 31767, then waits 

* indefinitely for connection requests. It calls ipcselect() to 

* test whether the call socket has a connection pending, and calls 

* ipcrecvcn to accept the connection. After a connection is 

* established, the client will send in a person's name, with which 

* the server will search the database file for information for that 

* person. If found, the information will be returned. This process 

* continues until the virtual socket becomes exceptional; in which 

* case, ipcshutdown is called to shutdown that particular socket. 

*/ 

finclude <stdio.h> 

#include <string.h> 

#include <sys/ns_ipc.h> 

#define BUFFERLEN20 
#define INF0BUFLEN60 
#define CALL_S0CKET3 
#define INFINITE SELECT 1 
#define MAX_S0CKETS60 
#define MAX_BACKL0G5 
#define TCP_P0RT31767 


int call_sd; 

int call_sd_mask[2]; 

int rmap[2], xmap[2]; 

int curr_rmap[2], curr_wmap[2], curr_xmap[2]; 

short offset; 

short control_value; 

ns_int_t result; 

FILE *datafile; 

short opt[40]; 

short opt_data; 

short opterr; 

short timeout; 

ns_int_t flags; 

short opt_num_arguments; 

ns_int_t sbound ; 

int soc_count; 
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extern void addopt(); 
extern void initopt(); 
extern void ipccontro1(); 
extern void ipccreate(); 
extern void ipcrecvcn(); 
extern void ipcrecv(); 
extern void ipcselect(); 
extern void ipcsend(); 
extern void ipcshutdown(); 

void Error_Routine(); 
void HandleNewRequestO; 
void Initialize_Option(); 
void ProcessRead(); 
int ReadData(); 
void SetUpO; 
void ShutdownVC(); 

main() 

{ 

int i; 


SetUpO; 


/* loop forever to serve clients. If any new client requests 

* service, the exception map will be set on the call socket. 

* If a client asks for information, the read map will be set 

* on the vc socket for that client. When the server detects 

* an exceptional condition on an existing vc socket, it means 

* that the corresponding client has shutdown. In which case, 

* both rmap and xmap are adjusted for the next ipcselect() call. 

* 


* If any other error situation occurs, both the name of the 

* previous ipc call and the error code is printed and the 

* process is terminated by an exit() call. 

*/ 

curr_rmap[0] = curr_rmap[l] = 0; 
curr_xmap[0] = curr_xmap[l] = 0; 
for(;;) 

{ 


for (i = 0; i < 2; i++ ) 
{ 

curr_rmap[i] = rmap[i]; 
curr_xmap[i] = xmap[i]; 

} 


timeout = -1; 
sdbound = MAX_S0CKETS; 


ipcselect( Ssbound, curr_rmap, curr_wmap, curr_xmap, 
timeout, &result); 
if (result) 

{ 
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Error_Routine(”ipcse1ect" f result, call_sd); 

} 

/* Check for read condition. 

*/ 

if ( (curr_rmap[0]) || (curr rmap[l]) ) 

{ 

for ( offset = 0; offset < sbound; offset++) 

{ 

if (curr_rmap[offset/323 & 

((unsigned int)0x80000000 »(offset %32))) 
ProcessRead( offset ); 

} 

} 

/* Check for new connection request. The bit in curr_xmap 

* for the call socket is clear, so that the call socket 

* will not be interpreted as a vc shutdown. 

*/ 

if (curr_xmap[call_sd/32] & 

((unsigned int)0x80000000 » (call_sd % 32)) ) 

{ 

HandleNewRequest(); 
curr_xmap[0] &= ca1l_sdjmask[0] ; 
curr_xmap[1] &= call_sd_mask[l]; 

} 

/* Check for vc shutdown. 

*/ 

if ( (curr_xmap[0]) || (curr_xmap[l]) ) 

{ 

for ( offset = 0; offset < sbound; offset++) 

{ 

if (curr_xmap[offset/32] & 

((unsigned int)0x80000000 »(offset %32))) 
ShutdownVC( offset ); 

} 


} 

} 

} 

void Error_Routine(where, what, sd) 
char *where; 
int what; 
int sd; 

{ 

printf("Server: Error occured in %s call.\n", where); 
printf("Server: The error code is: %5d. The local descriptor is:\ 
%d \n", what, sd); 
exit(); 

} 
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void HandleNewRequestO 

{ 

int vc_sd; 


/* Establish a connection for a new client. Adjust the xmap 

* and the rmap parameters of the ipcselect() call to reflect 

* the new connection. 

*/ 

Initialize_0ption( opt ); 
flags = 0; 

ipcrecvcn( call_sd, &vc_sd, &flags, opt, Sresult ); 
if (result) 

{ 

Error_Routine( ipcrecvcn , result, call_sd ); 

} 

/* set rmap and xmap for the new socket for subsequent ipcselect() 
* call. 

*/ 

rmap[vc_sd/32j = ((unsigned int) 0x80000000 » (vc_sd %32)); 
xmap[vc_sd/32] = ((unsigned int) 0x80000000 » (vc_sd %32)); 

/* Set the timeout to infinity with ipccontrol for later calls 

*/ 

flags = 0; 
control_value = 0; 

ipccontrol( vc_sd, NSC_TIME0UT_RESET, &control_value, 2, 0,0, 
&flags, &result ); 
if (result) 

{ 

Error_Routine( ipccontrol , result, call_sd ); 

} 


/* 

* Check if we have reached the maximum number of sockets. 

* If so, disallow any new requests by clearing the exception 

* map for the call socket. 

*/ 

if (++soc_count >= MAX_S0CKETS ) 

{ 

xmap[0] = ca1l_sd_mask[0]; 
xmap[1] = ca1l_sd_mask[1]; 

} 

} 

j 

void lnitialize_0ption() 

{ 

int opt_num_arguments; 
short opt_err; 
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opt_num_arguments = 0; 
initopt( opt, opt_num_arguments, &opt_err); 
if ( opt_err ) 

{ 

Error_Routine( initopt , opt_err, 0); 

} 

} 

jj 

void ProcessRead( offset ) 
short offset; 

{ 

int buffer len; 

char client_buf[BUFFERLEN + 1]; 
char data_buf[INFOBUFLEN]; 
int vc_sd; 


/* The client with socket discriptor 'offset' has sent in a name. 

* The server will recieve that name and search for the information 

* in the database file. If found, the information will be sent 

* back to the client, otherwise, a ’not found' message will be 

* sent. 

*/ 

Initialize_0ption( opt ); 
vc_sd = offset; 
buffer Jen = BUFFERLEN; 
flags = 0; 

ipcrecv( vc_sd, client_buf, &buffer_len, &flags, opt, &result ); 
if (result) 

{ 

Error Routine( ipcrecv , result, vc_sd); 

} 

client_buf[BUFFERLEN] = 0; 

if (!ReadData( client_buf, data_buf )) 

{ 

printf("Server; %s not in file.\n", client_buf); 
sprintf(data_buf, SERVER did not find the requested name \ 
in the datafile. \n ); 

} 


bufferjen = INFOBUFLEN; 
flags = 0; 

ipcsend( vc_sd, data_buf, bufferjen, &flags, opt, Sresult); 
if ( result ) 

{ 

Error_Routine ("ipcsend", result, vc_sd); 

} 

} 
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int ReadOata (client_buf, output_buf) 
char *c1ient_buf; 
char *output_buf; 

{ 

chart_buf [80 ]; 


/* Sequentially read the database file until the name is found 

* or EOF is reached. Return 1 if the name is located, 0 

* otherwise. 

*/ 

rewind( datafile ); 
for(;;) 

{ 

if (fgets(t buf, 80, datafile)) 

{ 

if (!strncmp(client_buf, t_buf, BUFFERLEN)) 

{ 

strncpy(output_buf, &(t_buf[BUFFERLEN]), 

INFOBUFLEN); 

printf("Server: %s information found.\n", 
client_buf); 
return(l); 

} 

} 

else 

{ 

return(0); 

} 

} 

} 

void SetUpO 

{ 

/* Open the database file for reading. 

*/ 

if ((datafile = fopen("datafile", r )) == NULL) 

{ 

Error_Routine( fopen , 0, 0); 

} 


/* Set up the opt array for the two parms we will use 

*/ 

opt_num_arguments = 2; 
initopt( opt, opt_num_arguments, &opterr); 
if (opterr) 

{ 

Error_Routine( initopt , opterr, call sd ); 

} 


/* Set TCP port address 
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*/ 

opt_data = TCP_PORT; 

addopt( opt, 0, NS0_PR0T0C0L_ADDRESS, 2, &opt_data, &opterr); 
if (opterr) 

{ 

Error Routine( addopt , opterr, call sd); 

} 


/* Set maximum number of connection requested can be pend at 
* one time. 

*/ 

opt_data = MAX_BACKLOG; 

addopt( opt, 1, NS0_HAX_C0NN_REQ_BACK, 2, &opt_data, &opterr); 
if (opterr) 

{ 

Error_Routine( addopt , opterr, call sd); 

} 


/* Create new call socket. 

*/ 

flags = 0; 

ipccreate( NS_CALL, NSP_TCP, &flags, opt, &call_sd, &result); 
if (result) 

{ 

Error Routine( ipccreate , result, call_sd); 

} 


/* Set the time out value for subsequent ipcrecvcn() call to 

* infinity. The program will suspend indefinitely on an 

* ipcrecvcn() call. 

*/ 

flags = 0; 
control_value = 0; 
timeout =0; 

ipccontrol( call_sd, NSC_TIME0UT_RESET, &timeout, 2, 0, 0, 
&flags, Sresult); 
if (result) 

{ 

Error Routine( ipccontrol , result, call_sd); 

} 


/* Update soc_count to the number of socket descriptor used so 

* far. Set the xmap bit for the newly created call socket for 

* the next ipcselect() call. Save the one's compliment of xmap 

* for clearing the xmap bit for this call socket later. 

*/ 

soc_count++; 

xmap [call_sd/32] |= (((unsigned int) 0x80000000) » (call_sd % 32)); 
ca1 l_sd_mask[0] = -xmap[0]; 
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call sdjmask[l] = ~xmap[l]; 

> 

^**************************************************************************i 

void ShutdownVC(offset) 
short offset; 

{ 

int vc_sd; 
flags = 0; 

Initialize_0ption( opt ); 
vc_sd = offset; 

ipcshutdown( vc_sd t &flags, opt, Sresult ); 
soc_count ; 
if ( offset < 32 ) 

{ 

rmap[offset/32] &= -((unsigned int) 0x80000000 » (offset % 32)); 
xmap[offset/32] &= -((unsigned int) 0x80000000 » (offset % 32)); 

} 

xmap[call_sd/32] |= ((unsigned int) 0x80000000 » (call sd % 32)); 

} 
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Example 6: Cross-System Client in C 

/* NETIPC C-REQUESTER EXAMPLE 
* 

* This program initiates a connection to a remote well known 

* socket at TCP port 31767. After the connection is established, 

* The program will prompt the user to input a person's name from 

* the terminal. The name will be sent to the server process. In 

* return, the server will send back the associate information about 

* that person if it exists in the database file. This process 

* repeats until the user inputs an 'EOT' message. In which case, 

* the program calls ipcshutdownQ to terminate the process. 

* 

*/ 


#include <stdio.h> 

#include <string.h> 

#include <sys/ns ipc.h> 

#define 0PT_SIZE 40 

fdefine NAMELEN 20 

#define BUFLEN 80 

main () 

{ 

ns_int_t vc_desc, dest_desc; 
ns_int_t result; 
short opt[0PT_SIZE]; 

short opterr; 

ns_int_t flags; 
char nodename[NAMELEN]; 
char namebuf[BUFLEN]; 
char readbuf[BUFLEN]; 

ns_int_t readlen; 
short timeout; 
static char E0Tbuf[ ] = EOT 
short TCP_port; 

int i; 

int shutdown = 0; 


/* Obtain the nodename from the user in which the well know 
* port 31767 is located. 

*/ 

printf("Client: Enter the remote node name: ); 
gets(nodename); 

initopt (opt, 0, &opterr); 

flags = NSF_DUP_DEST; 

TCP_port = 31767; 

ipcdest (N$_CALL, nodename, strlen(nodename), NSP_TCP, 
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&TCP_port, 2, &f1ags, opt, &dest_desc, fcresult); 
if (result) goto fatal_error; 


/* initialize connection request to server */ 

ipcconnect (-1, dest_desc, 8tflags, opt, &vc_desc, &result); 
if (result) goto fatal_error; 

/* release destination descriptor since it's not needed 
any more */ 

ipcshutdown (dest_desc, Sflags, opt, &result); 
if (result) goto fatal_error; 


/* set vc socket timeout to infinite, then confirm connection */ 
timeout = 0; 

ipccontrol (vc_desc, NSC_TIMEOUT_RESET, timeout, 2, readbuf, 

& readlen, Sflags, Sresult); 
if (result) goto fata1_error; 

ipcrecv (vc_desc, readbuf, &readlen, &flags, opt, &result); 
if (result) goto fatal_error; 

while([shutdown) 

{ 

/* get name from standard input */ 

printf ("Client: Enter name for data retrieval: ); 
gets (namebuf); 

for (i = strlen(namebuf); i < NAMELEN; i++) 

{ 

namebuf[i] = ' 

} 

namebuf[NAMELEN] = (char) 0; 

if (!strncmp(namebuf, EOTbuf, NAMELEN)) 

{ 

flags = 0; 

ipcshutdown (vc_desc, &flags, opt, Sresult); 
shutdown = 1; 
exit(0); 

} 

flags = 0; 

ipcsend (vc_desc, namebuf, 20, Sflags, opt, &result); 
if (result) goto return_error; 

flags = 0; 
readlen =60; 

ipcrecv (vc_desc, readbuf, Sreadlen, Sflags, opt, Sresult); 
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readbuf[readlen] = (char) 0; 

printf ("Client data is: %s\n”, readbuf); 

if (result) goto fatal_error; 

} 

return_error: exit(O); 

fatal_error: printf ("Client: fatal error: %d\n”, result) 
exit (result); 

} 
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Example 7: Cross-System Server in FORTRAN 

Header File 

$ALIAS ipcconnect (%val,%val,%ref,%ref,%ref,%ref) 

$ALIAS ipccontrol (%val,%val,%ref,%val,%ref,%ref,%ref,%ref) 

$ALIAS ipccreate (%val,%val,%ref,%ref,%ref t %ref) 

$ALIAS ipcdest (%va1,%ref f %va1,%va1 f %ref,%va1,%ref,%ref,%ref,%ref) 

$ALIAS ipclookup (%ref,%val,%ref,%val,%ref,%ref,%ref,%ref,%ref) 

$ALIAS ipcname (%val,%ref,%val,%ref) 

$ALIAS ipcnamerase (%ref,%val,%ref) 

$ALIAS ipcrecv (%val,%ref,%ref,%ref,%ref,%ref) 

$ALIAS ipcrecvcn (%val,%ref,%ref,%ref,%ref) 

$ALIAS ipcselect (%ref,%ref,%ref,%ref,%va1,%ref) 

$ALIAS ipcsend (%val,%ref,%val,%ref,%ref,%ref) 

$ALIAS ipcshutdown (%val,%ref,%ref,%ref) 

$ALIAS addopt (%ref,%va1,%val,%va1,%ref r %ref) 

$ALIAS initopt (%ref,%va1,%ref) 

$ALIAS readopt (%ref,%va1,%ref,%ref,%ref,%ref) 

$ALIAS istrlen = 'strlen' (%ref) 

SAL IAS OPEN = 'open' (%ref,%val) 

COMMONS File 

Integer*4 MAX_DESC 

Integer*2 here, active_VC, option(14), result 

Inter*4 call_socket_des, VC_socket_descriptor, flags_array, 

> error_return, VC_DES 

Integer*4 sdbound, current_rmap(2), readmap(2), writemap(2), 

> exceptionmap(2) 

LOGICAL bit_test 

common MAX_DESC 

common here, active_VC, option, result 

common ca1l_socket_des, VC_socket_descriptor, flags_array, 

> error_return, VC_DES 

common sdbound, current_rmap, readmap, writemap, 

> exceptionmap 

program server 
Include header 

C This program is the peer process to requester. It uses sockets in 
C synchronous mode to received a connection and message 

Implicit none 
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Integer*2 SIGCLD, SIG_IGN 

Integer*2 Itime, readdata, backlog, address, opt_num_arguments 

Integer*2 opt_num, opt code, len, OPEN, oflag 

Integer*2 TCP, MAX_BACKLOG, SYNCH_TIMEOUT, CALL_SOCKET, INFINITE 

Integer*4 socket_kind, protocol_kind, timeout, request, rlen, 

> win, fork, filenum, oldnum 

Character filename*16 
Include commons 

PARAMETER (SIGCLD = 1, SIG_IGN = 1) 

PARAMETER (filename = 'datafile' // char(O)) 

PARAMETER (oflag = 0) ! read only 

DATA MAX_BACKL0G/5/, SYNCH_TIME0UT/3/, TCP/4/, CALL SOCKET/3/, 

> INFINITE/0/ 

MAX_DESC = 63 

if(fork() .ne. 0) stop 
call setpgrp 

call signal (SIGCLD, SIG_IGN) 

C Open database file 'datafile' needed to service clients. 

filenum = OPEN (filename, oflag) 
call FSET (5, filenum, oldnum) 

C Initialize options to contain 2 parameters. 

opt_num_arguments = 2 

call initopt(option,opt_num_arguments,result) 
here = 1 

IF(result.NE.O) call CLEANUP 

The Addopt was added to the Server to assign a TCP address 
during the Ipccreate call. ’128' is the option code equivalent 
to the predefined constant 'NS0_PR0T0C0L_ADDRESS' in C 

opt_num = 0 
opt_code =128 
len = 2 

Address = 31767 

call addopt(option, opt_num, opt_code, len. Address,result) 
here = 2 

If(result .ne. 0) call CLEANUP 

C Set max backlog of pending connection request to 10 

opt_num = 1 
opt_code = 6 
len = 2 

backlog = MAX_BACKL0G 
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call addopt(option,opt_num, opt_code, len, backlog,result) 
here = 3 

IF(result .NE. 0) call CLEANUP 

C socket_kind is set to 3 and protocol_kind is set to 4 to 
C specify a call Socket and the TCP protocol for the following 

C IPCCREATE call. 

C The flags parameter is not used in this program, so flags_array 

C is made a double integer and assigned the value zero to ensure 

C that all the bits are clear. 

socket_kind = CALL_S0CKET 
protocol_kind = TCP 
flags_array = 0 

C A call Socket is created by calling IPCCREATE. The value returned 

C in the call_socket_descriptor parameter will be referenced by sub- 

C sequent IPC calls. 

call ipccreate(socket_kind,protoco1_kind,f1ags_array,option, 

>ca1l_socket_des,error_return) 
here = 4 

IF(error_return.NE.O) call CLEANUP 

C IPCCONTROL is used to set synchronous timeout to infinity. 

flags_array = 0 
win = 2 

request = SYNCH_TIME0UT 
Itime = INFINITE 

call ipccontro1(ca1l_socket_des,request,11ime,w1n,readdata,r1en, 

>f1ags_array,error_ret urn) 

Here = 5 

IF (error_return .NE. 0) call CLEANUP 

C check call Socket descriptors to check which ones are exceptional 

C (connection request pending) and which ones are readable. 

timeout = -1 ! infinity timeout 

sdbound = MAX_DESC 
writemap(l) = 0 
writemap(2) = 0 
exceptionmap(l) = 0 
exceptionmap(2) = 0 
current_rmap(l) = 0 
current_rmap(2) = 0 
active_VC = 1 

C First time through, set bit mask to recieve connection(s) on 
C newly allocated call socket. 

call bit_set(exceptionmap, call_socket_des) 

DO WHILE (.TRUE.) 

call ipcselect(sdbound, readmap, writemap, exceptionmap. 
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> timeout, error_return) 
here = 7 

IF (error_return .NE. 0) call CLEANUP 

IF ((readmap(l) .NE. 0) .OR. (readmap(2) .NE. 0)) call get_data 
IF ((exceptionmap(l) .NE. 0) .OR. 

> (exceptionmap(2) .NE. 0)) THEN 
call process xmap 

ENDIF 

sdbound = MAX_DESC 

writemap(l) = 0 

writemap(2) = 0 

readmap(l) = current_rmap(l) 

readmap(2) = current_rmap(2) 

exceptionmap(l) = current_rmap(l) 

exceptionmap(2) = current_rmap(2) 

IF (active_VC .LT. MAX_DESC) 

> call bit_set(exceptionmap, call_socket_des) 

END DO 

END 

subroutine process_xmap 

CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC 

Subroutine process_xmap receives new connections 
or shutsdown aborted VC connections. 

CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC 

Include header 

Implicit none 

Integer*2 opt_num_arguments 
Include commons 

C Reset the opt array to 0 so IPCRecvCn and IPCShutdown don't yell at 

flags_array = 0 
opt_num_arguments = 0 

CALL INIT0PT(option,opt_nujn_arguments,result) 

C get a new VC_socket_descriptor for the new connection. 

C Set appropriate bit of readmap used later by IPCSELECT. 

IF (bit_test(exceptionmap, call_socket_des)) THEN 

call IPCRECVCN(ca1l_socket_des,VC_socket_descriptor, 

> flags_array,option,errorjreturn) 
here = 8 

IF (error_return .NE. 0) call CLEANUP 
call bit_set(current_rmap, VC_socket descriptor) 

END IF 
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Check to see if VC sockets are exceptional conditions (aborted). 
If so, shutdown socket and clear update readmap mask for next 
IPCSELECT call. 

VC_DES = 0 

call bit_clear(exceptionmap, call_socket_des) 

DO WHILE ((exceptionmap(l) .NE. oj .OR. Iexceptionmap(2) .NE. 0)) 
IF(bit_test(exceptionmap, VC_DES)) THEN 
flags_array = 0 

call IPCSHUTDOWN(VC DES, flags array, option, error_return) 
IF (result .NE. 0) call CLEANUP 
active_VC = active_VC - 1 
call bit_clear(exceptionmap, VC_DES) 
call bit clear(current_rmap, VC DES) 

“ END IF 

VC_DES = VC_DES + 1 
END DO 

END 

ccccccccccccccccccccccccccccccccccccccccccccc 

c 

C Subroutine recv_data receives data from VC 
C 

ccccccccccccccccccccccccccccccccccccccccccccc 

subroutine get_data 
Include header 
Implicit none 
Integer*2 index 

Integer*4 message_buffer_length 

Character name_requested*20, name*20, eof_message*60, 

> send_buffer*60 

Include commons 

Data eofjnessage/'does not appear in datafile'/ 


C IPCRECV is called to receive a request from client (requester). 

C First, received the name of item needed. 

VCJ3ES = 0 

DO WHILE ((readmap(l) .NE. 0) .OR. (readmap(2) .NE. 0)) 

IF(bit_test(readmap, VC_DES)) THEN 
flags_array = 0 
message_buffer_length = 20 
VC_socket_descriptor = VC_DES 
CALL IPCRECV(VC_socket_descriptor,name_requested, 

> mes sage_buff er_1ength,f1ags_array,option,error_ret urn) 
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here = 9 

IF (result .NE. 0) call CLEANUP 
call bit_clear(readmap, VC DES) 

END IF 

VC_DES = VC_DES + 1 

END DO 

C The data file (datafile) is read to locate the corresponding entry. 
C If found, return the information. Otherwise, notify the client. 

C 

£ *************************************************************** 

C * An EOF record must exists at the end of 'datafile’ to * 

C * terminate the sequential search. Otherwise the program * 

C * will hang when the name is not found * 

message_buffer length = 60 
REWIND (5) 

DO WHILE (.TRUE.) 

read(5, '(A20, A60)’, end = 98) name, sendjauffer 
IF (name_requested .EQ. name) THEN 
flags_array = 0 

CALL IPCSEND(VC_socket_descriptor,send_buffer, 

> message_buffer_length,flags_array,option,error_return) 
here =10 

IF(error_return.NE.O) call CLEANUP 
RETURN 
END IF 
END DO 
STOP 

98 message_buffer_length =60 

CALL IPCSEND(VC_socket_descriptor,eof_message, 

> message_buffer_length,flags_array,option,error_return) 
here =11 

IF (error return .NE. 0) call CLEANUP 

RETURN 

END 


CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC 

C 

C Routine cleanup 
C 

CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC 
subroutine cleanup 
Implicit none 
Include commons 
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WRITE(6,'("error_return error code : _’\I4)') error_return 

WRITE(6,*("result error code: _”,I4)') result 

WRITE(6,'("Program server at location: ",I4)') here 

STOP 

END 

ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc 

c 

C routine bit_set 
C 

ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc 

subroutine bit_set(map, bit) 

Implicit none 

integer*4 map(2) r bit 
integer*4 offset, MAX_DESC 

common MAX_DE$C 

offset =31 

IF (bit .LE. offset) THEN 
map(l) = ibset(map(l), (offset - bit)) 

ELSE 

map(2) = ibset(map(2), (MAX_DESC - bit)) 

END IF 
RETURN 
END 

CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC 

c 

C routine bit_clear 

C 

CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC 

subroutine bit_clear(map, bit) 

Implicit none 

integer*4 map(2), bit 
integer*4 offset, HAX_DESC 
common MAX_DESC 

offset =31 

IF (bit .LE. offset) THEN 
map(l) = ibclr(map(l), (offset - bit)) 

ELSE 

map(2) = ibclr(map(2), (MAX_DESC - bit)) 

END IF 
RETURN 
END 
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cccccccccccccccccccccccccccccccccccccccccccccccccccccccc 

routine bit_test 

cccccccccccccccccccccccccccccccccccccccccccccccccccccccc 

logical function bit_test(map, bit) 

integer*4 map(2), bit 
integer*4 offset, MAX_DESC 

common MAX_DESC 

offset =31 

IF (bit .LE. offset) THEN 
IF (btest(map(l), (offset - bit))) THEN 
bit_test = .TRUE. 

ELSE 

bit_test = .FALSE. 

ENDIF 

ELSE 

IF (btest(map(2), (MAX_0ESC - bit))) THEN 
bit_test = .TRUE. 

ELSE 

bit_test = .FALSE. 

ENDIF 

ENDIF 

END 
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Example 8: Cross-System Client in FORTRAN 

PROGRAM client 

C This program is the peer process to server. It uses sockets 

C in synchronous mode and sends a message to server. 

$ALIAS ipcconnect (%val,%val,%ref,%ref,%ref,%ref) 

SALIAS ipccontrol (%val,%val,%ref,%val,%ref,%ref,%ref,%ref) 

$ALIAS ipccreate (%val,%va1,%ref,%ref,%ref,%ref) 

$ALIAS ipcdest (%va1,%ref,%va1,%va1,%ref,%va1,%ref,%ref,%ref,%ref) 

SALIAS ipclookup (%ref,%val,%ref,%val,%ref,%ref,%ref,%ref,%ref) 

SALIAS ipcname (%val,%ref,%val,%ref) 

SALIAS ipcnamerase (%ref,%val,%ref) 

SALIAS ipcrecv (%val,%ref,%ref,%ref,%ref,%ref) 

SALIAS ipcrecvcn (%val,%ref,%ref,%ref,%ref) 

SALIAS ipcselect (%ref,%ref,%ref,%ref,%val,%ref) 

SALIAS ipcsend (%va1,%ref,%val,%ref,%ref,%ref) 

SALIAS ipcshutdown (%val,%ref,%ref,%ref) 

SALIAS addopt (%ref,%val,%val,%val,%ref,%ref) 

SALIAS initopt (%ref,%val,%ref) 

SALIAS readopt (%ref,%val,%ref,%ref,%ref,%ref) 

implicit none 

INTEGER*2 option(14), result, opt_num_arguments, counter, 

> protocol_addr 

INTEGER*4 socket_kind, protocol_kind, call_socket_descriptor, 

>error_return, VC_socket_descriptor, protocol_length, 

>message_buffer_length, location_length, data_length, 

>path_report_descriptor, protocol_returned, flags_array, 

>request, vlen, pi 

INTEGER*2 here, I, J, p2, timeout 

CHARACTER BLANK*1, E0T*3 

CHARACTER receive_buffer*60, send_buffer*20 

CHARACTER location*50, socket_name*8 

DATA EOT/'EOT '/, BLANK/’ 7 

C INITOPT is called to initialize the option parameter used in the 

C IPCCREATE, IPCDEST, IPCCONNECT, IPCRECV, IPCSEND and 

C IPCSHUTDOWN calls. By setting opt_num_arguments to zero, the 
C option parameter is initialized to contain zero entries. 


opt_num_arguments = 0 

CALL INITOPT(option,opt_num_arguments,resu1t) 
here = 1 

IF(result.NE.O) GO TO 99 
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socket_kind is set to 3 and protoco1_kind is set to 4 to specify 
a call socket and the TCP protocol for the following IPCCREATE 
call. 

The flags_array parameter is not used in this program so flags_array 
is made a double integer and assigned the value zero to ensure that 
all the bits are clear. 

socket_kind = 3 
protocol_kind = 4 
flags_array = 0 

A call socket is created by calling IPCCREATE. The value returned 
in the call_socket_descriptor parameter will be used in the following 
IPCCONNECT call. 

CALL IPCCREATE(socket_kind,protocol_kind,flags_array,option, 

>ca1l_$ocket_descriptor,error_return) 
here = 2 

IF(error_return.NE.O) GO TO 99 

write(6,*) ’Client: Enter the remote node name:’ 
read (5, ’(A50)’) location 
DO i = 1,50 
IF (location(i:i).EQ.” ) THEN 
location_length = i - 1 
GO TO 10 
ENDIF 

END DO 

10 CONTINUE 

flags_array = 0 
protocol_addr = 31767 
protocol_length = 2 

20 call ipcdest(socket_kind, location, location_length, 

> protocol_kind, protocol_addr, protocol_length, 

> flags_array, option, path_report_descriptor, 

> error_return) 
here = 3 

IF (error_return .NE. 0) GO TO 99 

counter = counter + 1 
here = 4 

IF (error_return.EQ.O) GO TO 30 
IF (error_return.NE.37) GO TO 99 
IF (counter.LE.10) THEN 
GO TO 20 

ELSE 

GO TO 99 

ENDIF 

flags_array =0 
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The ca11_socket_descriptor returned by IPCCREATE and the 
path_report_descriptor returned by IPCDEST are used in 
IPCCONNECT to request a connection with server. The 
VC_socket_descriptor returned by IPCCONNECT is used in subsequent 
calls to reference the connection. Once this call has completed 
successfully, you may optionally release the call socket descriptor 
by calling IPCSHUTDOWN in order to return resources to the system. 
Doing so will not affect the newly-created VC socket descriptor. 


30 CALL IPCCONNECT(call_socket_descriptor,pathjreport_descriptor, 
>f1ags_array,option,VC_socket_descriptor,error_ret urn) 

here = 5 

IF(error_return.NE.O) 60 TO 99 

flags_array = 0 
request = 3 ! timeout 

timeout = 0 ! infinite 

vlen = 2 


CALL IPCC0NTR0L (VC_socket_descriptor, request, timeout, vlen, pi, 
> p2, flags_array, error_return) 

here = 9 

IF (error_return .NE. 0) GO TO 99 

C IPCRECV is called to determine if the connection has been 
C established. 

flags_array = 0 
data_7ength = 60 

CALL IPCRECV(VC_socket_descriptor,receive_buffer,data_length, 

>flags_array,opt ion,error_return) 
here = 6 

IF(error_return.NE.O) GO TO 99 

C Loop forever till user types in 'EOT' in response. 

C Client will then terminate itself and let the networking code 

C clean up which will notify server via the exceptional condition 

C on the appropriate VC socket. 

DO WHILE (.TRUE.) 

40 write(6,*) 'Client: Enter name for data retrieval:' 

read (5, '(A20)') send_buffer 
IF (send_buffer .EQ. EOT) STOP 
IF (sendjbuffer .EQ. BLANK) THEN 

write(6,*) 'Type EOT to terminate.' 
go to 40 
END IF 

C Data is sent to server on the newly established connection. 
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flags_array = 0 
message_buffer_length = 20 

CALL IPCSEND(VC_socket_descriptor,send_buffer, 

> message_buffer_length,flags_array,option r error_return) 
here = 7 

IF(error_return.NE.O) GO TO 99 
C receives data from server 

message_buffer_length = 60 

CALL IPCRECV(VC_socket_descriptor f receive_buffer, 

> message_buffer_length, flags_array,option,error_return) 
here = 8 

IF (error jreturn .NE. 0) go to 99 
write(6,'(A20, $)') send_buffer 
write(6,'(A60)') receive_buffer 
END DO 

99 WRITE (6, '("result error code: - ,14)') result 

WRITE (6, '( error_return error code: ,14)') error_return 
WRITE (6, ’("Program requester at location: _",I4)') here 

100 STOP 
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Example 9: Cross-System Server in PASCAL 

PROGRAM server( input, output ); 


{ } 

{ 

{ SERVER: IPCSelect Server Sample Program 

{ Revision: <870610.1338> 

{ } 

{ 

{ 

{ } 

{ COPYRIGHT (C) 1987 HEWLETT-PACKARD COMPANY. 

{ All rights reserved. No part of this program may be photocopied, 

{ reproduced or translated into another programming language without 
{ the prior written consent of the Hewlett-Packard Company. 

{ } 

{ 

{ } 

{ Name : Server 

{ Source : 91790-18### 

{ Reloc : 91790-16### 

{ Prgmr : «lms» 

{ Date : <870610.1338> 

{ } 

{ 

{ 

{ PURPOSE: 

{ To show the operation of the IpcSelectO call. 

{ 

{ REVISION HISTORY 

O 

LABEL 


} 

} 

} 


99; 


CONST 


BUFFERLEN = 20; 
CALL_S0CKET = 3; 
CHANGE_BACKL0G = 6; 
CHANGE_TIME0UT = 3; 
FOREVER = TRUE; 
INFINITE_SELECT = -1; 
INFOBUFLEN = 60; 

INT16 LEN = 2; 
LENGTH_0F_DATA = 20; 
MAX_BACKL0G = 5; 
MAX_BUFF_SIZE = 1000; 
MAX_RCV_SIZE = 4; 
MAX_SEND_SIZE = 3; 
MAX_S0CKETS = 32; 
PROTO ADDR = 128; 
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TCP = 4; 
ZERO = 0; 


TYPE 

BitMapType = RECORD 
CASE Integer OF 

1: ( bits : PACKEO ARRAY[0..63] OF Boolean ); 

2: ( longint : Packed Array[1..2] OF Integer ); 

3: ( ints : ARRAY[1..4] OF Shortlnt ); 

END; 

byte = 0..255; 

byte_array_type = packed array [1..40] of byte; 
buffer_type = packed array [1..BUFFERLEN] of char; 
InfoBufType = packed array [1..INFOBUFLEN] of char; 
name_pf_call_array_type = packed array [1..10] of char; 
name_array_type = packed array [1..7] of char; 

VAR 


call_name 


name_of_ca1l_array_type; 

call_sd 


integer; 

control_value 


Shortlnt; 

currjrmap 


BitMapType; 

curr_wmap 


BitMapType; 

curr_xmap 


BitMapType; 

dummy_parm 


Integer; 

dummy_len 


Integer; 

error_return 


Integer; 

flags_array 


integer; 

map_offset 


Shortlnt; 

opt data 


Shortlnt; 

opt_num_arguments 

Shortlnt; 

option 


byte_array_type; 

protocol_kind 


Integer; 

rmap 


BitMapType; 

sbound 


Integer; 

short_error 


Shortlnt; 

socket_kind 


Integer; 

timeout 


Integer; 

timeout_len 


Integer; 

vc_count 


Integer; 

xmap 


BitMapType; 

$TITLE 'IPC Procedures', PAGE $ 
PROCEDURE ADDOPT 


(VAR opt 

byte_array_type; 


argnum 

Shortlnt; 


optcode 

Shortlnt; 


data_len 

Shortlnt; 


VAR data 

Shortlnt; 


VAR error 
EXTERNAL; 

Shortlnt); 
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PROCEDURE INITOPT 
(VAR opt : 

num_args : 
VAR error : 
EXTERNAL; 

PROCEDURE READOPT 
(VAR opt : 

argnum : 
VAR optcode : 
VAR data_len : 
VAR data 
VAR error : 
EXTERNAL; 


byte_array_type; 
ShortInt; 
Shortlnt); 


byte_array_type; 

Shortlnt; 

Shortlnt; 

Shortlnt; 

Integer; 

Shortlnt); 


PROCEDURE IPCControl 


socket 
request 
VAR wrtdata 
wrtlen 
VAR data 
VAR datalen 
VAR flags 
VAR result 
EXTERNAL; 


integer; 

integer; 

Shortlnt; 

Integer; 

Integer; 

Integer; 

Integer; 

Integer ); 


PROCEDURE IPCCREATE 
( socket : 

protocol : 
VAR flags : 
VAR opt : 
VAR csd : 
VAR result : 


integer; 

integer; 

integer; 

byte_array_type; 
integer; 
integer); 


EXTERNAL; 


PROCEDURE IPCNAME 

( descriptor : integer; 

VAR name : name_array_type; 

nlen : integer; 

VAR result : integer); 

EXTERNAL; 

PROCEDURE IPCRECVCN 

( csd : integer; 

VAR vcsd : integer; 

VAR flags : integer; 

VAR opt : byte_array_type; 

VAR result : integer); 

EXTERNAL; 


PROCEDURE IPCRECV 
( csd :integer; 

VAR data : buffer_type; 
VAR dlen : integer; 
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VAR flags : integer; 

VAR opt : byte_array_type; 
VAR result : integer); 
EXTERNAL; 

PROCEDURE IPCSelect 
(VAR sbound : Integer; 

VAR rmap : BitMapType; 

VAR wmap : BitMapType; 

VAR xmap : BitMapType; 

timeout: Integer; 

VAR result : Integer ); 
EXTERNAL; 


PROCEDURE IPCSEND 


( vcsd 
VAR data 
dlen 
VAR flags 
VAR opt 
VAR result 
EXTERNAL; 


integer; 

InfoBufType; 

integer; 

integer; 

byte_array_type; 
integer); 


PROCEDURE IPCSHUTDOWN 
( vcsd : integer; 

VAR flags : integer; 

VAR opt : byte_array_type; 

VAR result : integer); 

EXTERNAL; 

$ TITLE 'Internal Procedures', PAGE $ 

PROCEDURE Error_Routine 
(VAR where : name_of_call_array_type; 
what : integer; 
sd : integer); 

FORWARD; 

PROCEDURE HandleNewRequest; 

FORWARD; 

{ A new client wants to talk to us, complete the vc establishment 

PROCEDURE Initialize_0ption 

(VAR opt_parameter : byte_array_type); 

FORWARD; 

PROCEDURE ProcessRead 

( map_offset : ShortInt ); 

FORWARD; 

{ Process the read that is waiting on a particluar vc } 

PROCEDURE ReadData 

(VAR client_buf : Buffer_Type; 

VAR output_buf : InfoBufType ); 
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FORWARD; 

{ Read the data from the file, prepare for the IPCSend call. } 

PROCEDURE SetUp; 

FORWARD; 

{ Create a call socket using a well-known address } 

PROCEDURE ShutdownVC 

( map_offset : Shortlnt ); 

FORWARD; 

{ Shut down a vc that the client no longer needs } 


$ TITLE 'Error_Routine' f PAGE $ 

PROCEDURE Error_Routine 

(VAR where : name_of_call_array_type; 
what : integer; 
sd : integer); 

BEGIN { Error_Routine } 

writeIn('Server: Error occurred in ’, where,' call.' ); 
writeIn('Server: The error code is: what:5, 

The local descriptor is: sd:4 ); 


GOTO 99; 

END; { Error_Routine } 

$ TITLE 'HandleNewRequest', PAGE $ 

PROCEDURE HandleNewRequest; 

{ A new client wants to talk to us, complete the vc establishment } 
VAR 

result : Integer; 

vc_sd : Integer; 

BEGIN { HandleNewRequest } 

Initialize_Option( option ); 

{ Accept the connection for this new vc. } 

IPCRecvCn( call_sd, vc_sd, flags_array, option, result ); 

IF result <> ZERO THEN 
BEGIN { error on ipcrecvcn } 
call_name := 'IPCRECVCN '; 

Error_Routine(call_name,result, vc_sd ); 

END; { error on ipcrecvcn } 

{ Increment the total number of active vcs for the server } 
vc_count := vc_count + 1; 

{ Now set the read and exception maps for this new vc } 
rmap.bits[vc_sd] := TRUE; 
xmap.bits[vc_sd] := TRUE; 
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{ Set the timeout to infinity with IPCControl for later calls } 
flags_array := 0; 
control_value := 0; 
timeout_len := 2; 

IPCControl( vc_sd, CHANGE_TIMEOUT, control_value, timeout_len, 
dummy_parm, dummy_len, flags_array, error_return ); 

IF error_return <> ZERO THEN 
BEGIN 

ca1l_name := 'IPCC0NTR0L'; 

Error Routine( call_name,error return, vc_sd ); 

END; 


{} 

{ Check if we have reached the maximum number of sockets. 

{ If so, disallow any new requests by clearing the exception 
{ map for the call socket. 

{} 

IF vc_count = MAX_S0CKETS -1 THEN 
BEGIN { reached socket limit } 

xmap.bits[call_sd] := FALSE; 

END; { reached socket limit } 

END; { HandleNewRequest } 

$ TITLE ’Initialize_0ption ', PAGE $ 

PROCEDURE Initialize_0ption 

(VAR opt_parameter : byte_array_type); 

VAR 

opt_num_arguments : ShortInt; 
result : Shortlnt; 

BEGIN 

opt_num_arguments := 0; 

INITOPT( opt_parameter,opt_num_arguments,result ); 

IF result <> ZERO THEN 
BEGIN { error on initopt } 

call_name := 'INITOPT '; 

Error_Routine( call_name, result, 0 ); 

END; { error on initopt } 

END; {Initialize_0ption} 

$ TITLE ’ProcessRead', PAGE $ 

PROCEDURE ProcessRead 

( map_offset : Shortlnt ); 

{ Process the read that is waiting on a particluar vc } 

VAR 

buffer_len : Integer; 

client_buf : Buffer_type; 
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data_buf : InfoBufType; 

result : Integer; 

vc_sd : Integer; 

BEGIN { ProcessRead } 

{ There is a pending read on a vc. Do an IPCRecv on the vc } 
flags_array := 0; 

Initia1ize_0ption( option ); 

vc_sd := map_offset; 

{ Get the name this client wants data for } 
buffer Jen := BUFFERLEN; 

IPCRecv( vc_sd, client_buf, buffer_len, 
flags_array, option, result ); 

IF result <> ZERO THEN 

BEGIN { error on ipcrecv } 

call_name := 'IPCRECV '; 

Error_Routine( call_name,result,vc_sd ); 

END; { error on ipcrecv } 


{ Get the data we need from the file to send to the client } 
ReadData( client_buf, data_buf ); 
buffer Jen := INFOBUFLEN; 

IPCSendf vc_sd, data_buf, bufferjen, flags_array, 
option, result ); 

IF result <> ZERO THEN 

BEGIN { error on ipcsend } 

call_name := 'IPCSEND '; 

Error_Routine( call_name,result,vc_sd ); 

END; { error on ipcsend } 

END; { ProcessRead } 

$ TITLE 'ReadData', PAGE $ 

PROCEDURE ReadData 

(VAR client_buf : Bufferjype; 

VAR outputJuf : InfoBufType ); 

{ Read the data from the file, prepare for the IPCSend call. } 

CONST 


LAST_REC = 4; 

current_rec 

Shortlnt; 

datafile 

TEXT; 

info_buf 

InfoBufType; 

infofile 

Bufferjype; 

found 

Boolean; 

name_buf 

Bufferjype; 

BEGIN { ReadData } 
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{> 

{ Open the file named datafile . Search until the last record 
{ is found, or we match the user name the client wants. 

{ If there is a match, retreive the remaining data from the 
{ file, and prepare to send it back. 

{ 

{ If there is no match, return name not found to the client. 

{} 

found := FALSE; 
current_rec ■:= 1; 
infofile := 'datafile'; 

RESET( datafile, infofile ); 

WHILE ( NOT found ) AND ( current_rec <= LAST_REC ) DO 
BEGIN { search the file } 

READLN( datafile, name_buf, info_buf ); 

IF client_buf = name_buf THEN 
BEGIN { found a match } 

{} 

{ We found the name the client requested in the file. 

{ Set the flag to fall out of the while loop, and 
{ get the buffer to be sent to the client. 

0 

write In( 'Server: ', client_buf, ' information found.’ ); 

found := TRUE; 
outputJ>uf := info_buf; 

END; { found a match } 

{ increment to test the next record in the file } 
current_rec := currentjrec +1; 

END; { search the file } 


{} 

{ We've fallen out of the WHILE loop because there is a match, 

{ or we reached the end of the file. Find out which one it is. 

{} 

IF NOT found THEN 

BEGIN { didn't find the requested name } 

O 

{ We didn't find the data in the file. Put an error 
{ message in the data buffer. 

{} 

writeln ('Server: ', client_buf, ' not in file.' ); 
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output_buf := 

'SERVER did not find the requested name in the datafile. ’; 

END; { didn't find the requested name } 

END; { ReadData } 

$ TITLE 'Setup', PAGE $ 

PROCEDURE Setup; 

{ Create a call socket using a well-known address } 

BEGIN { SetUp } 

{ Set up the opt array for the two parms we will use } 
opt_num_arguments := 2; 

InitOpt( option, opt_num_arguments, short_error ); 

IF short_error <> ZERO THEN 
BEGIN { error on initopt } 
call_name := 'InitOpt'; 
error_return := short_error; 

Error_Routine( ca1l_name,error_return,ca1l_sd ); 

END; { error on initopt } 

{ Now add the option for the well-known address for the IPCCreate Call } 
opt_data := 31767; 

AddOpt( option, 0, PR0T0_ADDR, INT16_LEN, opt_data, short_error ); 

IF short_error <> ZERO THEN 
BEGIN { error on AddOpt } 
call_name := 'AddOpt'; 
error_return := short_error; 

Error_Routine( call_name,error_return,call_sd ); 

END; { error on AddOpt } 


{ Change the backlog queue to the maximum } 
opt_data := MAX_BACKL0G; 

AddOpt( option, 1, CHANGE_BACKLOG, INT16_LEN, opt_data, short_error ); 
IF short_error <> ZERO THEN 
BEGIN { error on AddOpt } 
call_name := ’AddOpt'; 
error_return := short_error; 

Error_Routine( call_name,error_return,call_sd ); 

END; { error on AddOpt } 

{ Prepare to create a call socket } 
socket_kind := CALL_S0CKET; 
protocol_kind := TCP; 

{ clear the flags array } 
flags_array := 0; 

0 

{A call socket is created by calling IPCCREATE. The value returned 
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{in the call sd parameter will be used in the following calls. 

{} 

IPCCREATE( socket_kind, protocol_kind, flags_array, option, 
call_sd, error_return ); 

IF error_return <> ZERO THEN 
BEGIN 

ca1l_name := 'IPCCREATE 

Error_Routine( call_name,error_return,can sd ); 

END; 

{ Set the call_sd timeout to infinity with IPCControl for later calls } 
flags_array := 0; 
control_value := 0; 
timeout_len := 2; 

IPCControl( call_sd, CHANGE_TIMEOUT, control_value, timeout_len, 
dummy_parm, dummy_len, flags_array, error_return ); 

IF error return <> ZERO THEN 
BEGIN - 

call_name := 'IPCCONTROL'; 

Error_Routine( call_name,error_return,call sd ); 

END; " 

{ Now set IPCSelect’s bit map for the call socket } 
xmap.bits[call_sd] ;= TRUE; 

END; { Setup } 

$ TITLE 'ShutdownVC', PAGE $ 

PROCEDURE ShutdownVC 

( map_offset : Shortlnt ); 

{ Shut down a vc that the client no longer needs } 

VAR 

result : Integer; 

vc_sd : Integer; 

BEGIN { ShutdownVC } 

{} 

{ The client shut down the vc, or it has gone down due to a 
{ Networking problem. Either way, merely accept the shutdown. 

{} 

flags_array := 0; 

Initialize_0ption( option ); 

vc_sd := map_offset; 

IPCShutdown( vc_sd, flags_array, option, result ); 

{ Don’t worry about errors here, since there isn't much we can do. } 

{ Decrement the number of active vcs } 
vc_count := vc_count -1; 
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{ Clear the read map and exception map bits for this vc } 
rmap.bits[map_offset] := FALSE; 
xmap.bits[map_offset] := FALSE; 

{} 

{ Always set the exception map for the call socket. That way 
{ we'll be sure to re-enable new requests if we were at the 
{ limit before this vc was shut down. 

{} 

xmap.bits[callsd] := TRUE; 

END; { ShutdownVC } 

$TITLE 'Server MAIN', PAGE $ 

BEGIN { Server } 

{ Create a call socket with a well known address for the clients to use. } 
SetUp; 

{} 

{ Loop forever waiting to serve clients. If any new clients request 
{ service, the exception map will be set on the call socket. If 
{ a client asks for information, the read map will be set on the 
{ vc socket for that client. When the client has received the data, 

{ it will shut down the vc, and the vc socket will have the exception 
{ map set. Handle each one of these cases in this loop. 

{ 

{ If any other situations occur, exit out of the loop, and let the 
{ NS clean up routines de-allocate the sockets for this server. 

{} 

WHILE FOREVER = TRUE DO 
BEGIN { Forever Do } 

0 

{ Set the bit masks to check for all the vcs that we own. 

{ The rmap & xmap variables are maintained by ProcessNewRequest 
{ and ShutdownVC. 

{} 

curr_rmap := rmap; 
curr_xmap := xmap; 


sbound := MAX_SOCKETS; 
timeout := INFINITE_SELECT; 

0 

{ Do an exceptional select on the call socket, and on all vcs 
{ we own. Do a read select on all the vc sockets. 

{} 

IPCSelect( sbound, curr_rmap, curr_wmap, curr_xmap, 
timeout, error_return ); 

IF error return <> ZERO THEN 
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BEGIN { Select Error } 

call_name := 'IPCSELECT '; 

Error_Routine( can_name,error_return,call_sd ); 

END; { Select Error } 

{ See if there are any clients requesting information } 

IF ( rmap.longint[l] <> 0 ) OR ( rmap.longint[2] <> 0 ) THEN 
BEGIN { Process read on VC sockets } 

{ We have someone to service. Find out who it is. } 

FOR map_offset := 1 TO MAX_SOCKETS DO 
BEGIN { check all vcs } 

IF curr_rmap.bits[map_offset] = TRUE THEN 
BEGIN { have read on a vc } 

{} 

{ We know the client who needs service, 

{ Do an IPCRecv, get the necessary data, 

{ and do an IPCSend to send it back. 

{} 

ProcessRead( map_offset ); 

END; { have read on a vc } 

END; { check all vcs } 

END; { Process read on VC sockets } 

{ See if any clients have sent a message to the call socket } 
IF curr_xmap.bits[call_sd] = TRUE THEN 

BEGIN { new request on the call socket } 

{} 

{ We have a new client, go do an IPCRecvCn, and set the 
{ bit masks to accept reads and exceptions on the new vc. 

O 

HandleNewRequest; 


{ Clear the call socket xmap bit to simplify the test for the vcs } 
curr_xmap.bits[call_sd] := FALSE; 

END; { new request on the call socket } 


{} 

{ If we get an exception on a vc socket, shut it down. The client 
{ knows to shut down a socket once it has received the data it needs. 
{} 

IF ( curr_xmap.longint[l] <> 0 ) OR ( curr_xmap.longint[2] <> 0 ) THEN 
BEGIN { check for errors on vc sockets } 

{ One vc had an exception, find out which one } 

FOR map_offset := 1 TO MAX_SOCKETS DO 
BEGIN { check all vcs } 


A-54 Sample NetIPC Programs 



IF curr_xmap.bits[map_offset] = TRUE THEN 
BEGIN { shut down the vc } 

{} 

{ Do an IPCShutdown on the vc, and clear 
{ its bit in both the read and exception maps. 

O 

ShutdownVC( map_offset ); 

END; { shut down the vc } 

END; { check all vcs } 

END; { check for errors on vc sockets } 

END; { Forever Do } 


99: 

0 

{ We have some problem, the NS cleanup routine will shut down 
{ All the sockets we own once the program has terminated. 

{} 

END. { Server } 
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Example 10: Cross-System Client in PASCAL 

PROGRAM C1ient( input, output ); 


{ > 

{ 

{ Client: IPCSelect Client Sample Program 

{ Revision: <870610.1327> 

{ } 

{ 

{ 

{ } 

{ COPYRIGHT (C) 1987 HEWLETT-PACKARD COMPANY. 

{ All rights reserved. No part of this program may be photocopied, 

{ reproduced or translated into another programming language without 
{ the prior written consent of the Hewlett-Packard Company. 

{ } 

{ 

{ } 

{ Reloc : 91790-16### 

{ Prgmr : «lms» 

{ Date : <870610.1327> 

{ } 

{ 

{ 

{ PURPOSE: 

{ To show the operation of the IpcSelect() call. 

{ 

{ REVISION HISTORY 

0 

LABEL 

89, 

99; 


} 

} 

} 


CONST 


BUFFERLEN = 20; 
CALL_S0CKET = 3; 
CHANGE TIMEOUT = 3; 
FOREVER = TRUE; 
INFINITE_SELECT = -1; 
INFOBUFLEN = 60; 
INT16J.EN = 2; 
LENGTH_0F DATA = 20; 
MAX BUFFJIZE = 1000; 
MAX~RCV SIZE = 4; 
MAX_SEND SIZE = 3; 

MAX SOCKETS = 32; 
INTEGER LEN = 2; 

TCP = 4; 

ZERO = 0; 
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TYPE 


BitMapType = RECORD 
CASE Integer OF 

1: ( bits : PACKED ARRAY[1..32] OF Boolean ); 

2: ( longint : Integer ); 

3: ( ints : ARRAY[1..2] OF ShortInt ); 

END; 

byte = 0..255; 

byte_array_type = packed array [1..8] of byte; 
buffer_type = packed array [1..BUFFERLEN] of char; 
InfoBufType = packed array [1..INFOBUFLEN] of char; 
name_of_call_array_type = packed array [1..10] of char; 
name_Array_type = packed array [1..7] of char; 

VAR 


buffer_len 


Integer; 

call_name 


name_of_ca1l_array_type; 

call_sd 


integer; 

control_value 


Shortlnt; 

data_buf 


InfoBufType; 

dummy_1en 


Integer; 

dummy_parm 


Integer; 

error_return 


Integer; 

f lags_array 


integer; 

node_name 


Buffer_Type; 

node_name_len 


Integer; 

opt data 


Shortlnt; 

opt_num_arguments 

Shortlnt; 

option 


byte_array_type; 

proto_addr 


Shortlnt; 

protocol_kind 


Integer; 

req_name_len 


Integer; 

requested_name 


Buffer_Type; 

short_error 


Shortlnt; 

socket_kind 


Integer; 

temp_position 


Shortlnt; 

timeout 


Integer; 

timeout_len 


Integer; 

vc_sd 


Integer; 

$TITLE 'IPC Procedures', PAGE $ 


PROCEDURE ADDOPT 

(VAR opt 

byte_array_type; 


argnum 

ShortInt; 


optcode 

ShortInt; 


data len 

Shortlnt; 


VAR data 

ShortInt; 


VAR error 

Shortlnt); 


EXTERNAL; 

PROCEDURE INITOPT 

(VAR opt 

byte_array_type; 
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num_args : Shortlnt; 

VAR error : Shortlnt); 

EXTERNAL; 

PROCEDURE IPCConnect 

( ca11_sd : Integer; 

pathdesc : Integer; 

VAR flags : Integer; 

VAR opt : Byte_array_type; 

VAR vc_sd : Integer; 

VAR error : Integer); 

EXTERNAL; 

PROCEDURE IPCControl 

( socket : integer; 

request : integer; 

VAR wrtdata : Shortlnt; 

wrtlen : Integer; 

VAR data : Integer; 

VAR datalen : Integer; 

VAR flags ; Integer; 

VAR result : Integer ); 

EXTERNAL; 

PROCEDURE IPCCREATE 

( socket : integer; 

protocol : integer; 

VAR flags : integer; 

VAR opt : byte_array_type; 

VAR csd : integer; 

VAR result : integer); 

EXTERNAL; 

PROCEDURE IPCNAME 

( descriptor : integer; 

VAR name : name_array_type; 

nlen : integer; 

VAR result : integer); 

EXTERNAL; 

PROCEDURE IPCDEST 

( sock_kind : Integer; 

VAR node_name : BufferJType; 
name_len : Integer; 
protocol : Integer; 

VAR protoaddr : Shortlnt; 

proto_len : Integer; 

VAR flags : integer; 

VAR opt : byte_array_type; 

VAR pathdesc : Integer; 

VAR result : Integer); 
EXTERNAL; 
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PROCEDURE IPCRECVCN 

( csd : integer; 

VAR vcsd : integer; 

VAR flags : integer; 

VAR opt : byte_array_type; 

VAR result : integer); 

EXTERNAL; 

PROCEDURE IPCRECV 
( csd :integer; 

VAR data : InfoBufType; 

VAR dlen : integer; 

VAR flags : integer; 

VAR opt : byte_array_type; 

VAR result : integer); 

EXTERNAL; 

PROCEDURE IPCSelect 
(VAR sbound : Integer; 

VAR rmap : BitMapType; 

VAR wmap : BitMapType; 

VAR xmap : BitMapType; 

timeout: Integer; 

VAR result : Integer ); 

EXTERNAL; 

PROCEDURE IPCSEND 

( vcsd : integer; 

VAR data : buffer_type; 

dlen : integer; 

VAR flags : integer; 

VAR opt : byte_array_type; 

VAR result : integer); 

EXTERNAL; 

PROCEDURE IPCSHUTDOWN 
( vcsd : integer; 

VAR flags : integer; 

VAR opt : byte_array_type; 

VAR result : integer); 

EXTERNAL; 

$ TITLE 'Internal Procedures', PAGE $ 

PROCEDURE GetLen 

(VAR buffer : Buffer_Type; 

VAR current_pos : Shortlnt; 

VAR length : Integer ); 

FORWARD; 

{ Get the length of a string. Return the next postion } 

PROCEDURE Error_Routine 

(VAR where : name_of_call_array_type; 
what : integer; 
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sd : integer); 

FORWARD; 

PROCEDURE Initia1ize_0ption 

(VAR opt parameter : byte_array_type); 

FORWARD? 

PROCEDURE SetUp; 

FORWARD; 

{ Create a call socket, connect to server using IPCDest } 

PROCEDURE ShutdownSockets; 

FORWARD; 

{ Shut down the call and vc sockets } 


$ TITLE 'Error_Routine', PAGE $ 

PROCEDURE Error_Routine 

(VAR where : name_of_call_array_type; 
what : integer; 
sd : integer); 

BEGIN { Error_Routine } 

writeln('Client: Error occurred in where,' call.' ); 
writeln('Client: The error code is: ', what:5, 

The local descriptor is: ', sd:4 ); 


GOTO 89; 

END; { Error_Routine } 

$ TITLE 'GetLen', PAGE $ 

PROCEDURE GetLen 

(VAR buffer : Buffer_Type; 

VAR current_pos : ShortInt; 

VAR length : Integer ); 

{ Get the length of a string. Return the next post ion } 

VAR 

orig_pos : Short Int; 

BEGIN { GetLen } 

0 

{ Find the first blank in the string. Return the difference 
{ between the blank position, and the initial value of current pos 
{} 

orig_pos := current_pos; 

WHILE buffer[current_pos] <> ' ' DO 
current_pos := current_pos + 1; 
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{ set the length value for the caller } 
length := current_pos - orig_pos; 

{ increment beyond the space, for the next time } 
current_pos := current_pos + 1; 

END; { GetLen } 

$ TITLE 'Initialize_0ption PAGE $ 

PROCEDURE Initialize_0ption 

(VAR opt_parameter : byte_array_type); 

VAR 

opt_num_arguments : Shortlnt; 
result : Shortlnt; 

BEGIN {Initialize_0ption} 

opt_num_arguments := 0; 

INITOPT( opt_parameter,opt_num_arguments,result ); 
IF result <> ZERO THEN 
BEGIN { error on initopt } 
ca1l_name := 'INITOPT 
Error_Routine{ call_name, result, 0 ); 

END; { error on initopt } 

END; {Initialize_Option} 


$ TITLE 'SetUp', PAGE $ 

PROCEDURE SetUp; 

{ Create a call socket using a well-known address } 
VAR 

pathdesc : Integer; 

BEGIN { SetUp } 

{ Prepare to create a call socket } 
socket_kind := CALL_SOCKET; 
protocol_kind := TCP; 


{ clear the flags and option arrays } 
flags_array := 0; 

Initialize_0ption( option ); 

{} 

{A call socket is created by calling IPCCREATE. The value returned 
{in the call_sd parameter will be used in the following calls. 

O 

IPCCREATE( socket_kind, protocol_kind, flags_array, option, 
call_sd, error_return ); 
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IF error return <> ZERO THEN 

begin" 

calljiame := 'IPCCREATE ’; 

Error Routine( calIjiame,error return, call sd ); 

END; " 

0 

{ The server is waiting on a well-known address. Get the path 
{ descriptor for the socket from the remote node. 

{} 

proto_addr := 31767; 
flags_array ;= 0; 

IPCDest( socket_kind, node_name, node_name_len, protocol_kind, 
proto_addr, INTEGERJ.EN, flags_array, option, 
pathdesc, error_return ); 

IF error return <> ZERO THEN 
BEGIN 

calljiame := ’IPCDEST '; 

Error Routine( call name,error_return, pathdesc ); 

END; " 

flags_array := 0; 

{ Now connect to the server } 

IPCConnect( call_sd, pathdesc, flags_array, option, 
vc_sd, error_return ); 

IF error return <> ZERO THEN 
BEGIN" 

calljiame := 'IPCCONNECT’; 

Error_Routine( call name,error return, pathdesc ); 

END; 

{ Set the timeout to infinity with IPCControl for later calls } 
flags_array := 0; 
control_value := 0; 
timeout_len :— 2; 

IPCControl( vc_sd, CHANGE_TIMEOUT, control_value, timeout_len, 
dummy_parm, dummy_len, flags_array, error_return ); 

IF error_return <> ZERO THEN 
BEGIN 

calljiame := ’IPCCONTROL’; 

Error_Routine( calIjiame,errorjreturn, vc sd ); 

END; " 

flags_array := 0; 
lnitialize_0ption( option ); 

0 

{ Verify the server received the connect req. Wait for the 
{ server to do an IPCRecvCn. 

{} 
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IPCRecv( vc_sd, data_buf, buffer_len, flags_array t 

option, error_return ); 

IF error j*eturn <> ZERO THEN 
BEGIN 

calljiame := 'IPCRECV ’; 

Error_Routine( calljiame,error return, vc sd ); 

END; 

END; { Setup } 

$ TITLE 'ShutdownSockets', PAGE $ 

PROCEDURE ShutdownSockets; 

VAR 

result : Integer; 

BEGIN { ShutdownSockets } 

0 

{ We are terminating this program. Clean up the allocated 
{ sockets. 

{} 

flags_array := 0; 

Initialize_Option( option ); 

IPCShutdown( vc_sd, flags_array, option, result ); 

{ Don't worry about errors here, since there isn’t much we can do. } 

IPCShutdown( call_sd, flags_array, option, result ); 

{ Don't worry about errors here, since there isn’t much we can do. } 

END; { ShutdownSockets } 

$TITLE 'Client MAIN’, PAGE $ 

BEGIN { Client } 

node_name_len := 0; 
requested_name := "; 

{ Ask the user for the NS node name of the remote node } 

Prompt( 'Client: Enter the remote node name: ’ ); 

Readln( node_name ); 

temp_position := 1; 

GetLen( nodejiame, temp_position, nodejiame_len ); 

{ Create a call socket and connect to the server } 

SetUp; 

WHILE requestedjiame <> 'EOT' DO 
BEGIN { loop for name } 

{ Ask the user for a name to be retrieved } 

Prompt( 'Client: Enter name for data retrieval: ' ); 

ReadIn( requestedjiame ); 
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req_name_len := BUFFERLEN; 
flags_array := 0; 

IF requested_name <> 'EOT' THEN 
BEGIN { continue processing } 

{ Ask for the name the user requested } 

IPCSend( vc_sd f requested_name r req_name_len, flags_array, option, 
error_return ); 

{ Block waiting for the response back from the server. } 
bufferjen := INFOBUFLEN; 
flags_array := 0; 

IPCRecv( vc_sd, data_buf, buffer_len, flags_array, option, 
error_return ); 

IF error_return <> ZERO THEN 
BEGIN { error on initopt } 
call_name : = 'IPCRECV '; 

Error_Routine( call_name, error_return, vc_sd ); 

END; { error on initopt } 

{ Print out the data received } 

Writeln( 'Client data is: ', data_buf ); 

END; { continue processing } 

END; { loop for name } 

89: 

{ Clean up the call and vc sockets } 

ShutDownSockets; 

99: 


END. { Client } 
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B 


Error Messages 


This appendix lists and describes the messages that can be returned to the result 
and error parameters of NetIPC calls. The ASCII message associated with each code 
can be used in C programs. These constants are listed in the NS include file 
/usr/i ncl ude/sys/ns_i pc .h. 

0 

MESSAGE 

NSRNOERROR 


CAUSE 

The call was successful. 


ACTION 

No action is necessary. 

3 

MESSAGE 

NSR_BOUNDS_VI0 


CAUSE 

Parameter bounds violation. 


ACTION 

An address references memory to which the user does not 
have access rights. 

4 

MESSAGE 

NSRNETWORKDOWN 


CAUSE 

The network is down. The system is not initialized for 
networked operation. 


ACTION 

Use ifconf ig 1 anO to see if the “down” flag is displayed. 

If not, this may be an internal error. Consult your 

Network Manager. 
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5 

MESSAGE 

NSR_SOCK_KIND 


CAUSE 

Illegal socket kind. The calling process attempted to 
create a kind of socket that the system does not support. 


ACTION 

Check the socket kind parameter to make sure it matches 
one of the socket kind supported by the system. 

6 

MESSAGE 

NSRPROTOCOL 


CAUSE 

Illegal protocol. The protocol referenced is not supported 
by the system. 


ACTION 

One or more of the following actions may be taken: (1) 
Check the protocol parameter to make sure it matches 
one of the protocol types supported by the system; (2) 
make sure the system supports the referenced protocol; (3) 
consider defaulting the protocol argument to zero, thus 
letting the system decide which protocols are best. 

7 

MESSAGE 

NSR_FLAG$ 


CAUSE 

Illegal flags. A fl ags bit was set that is not supported. 


ACTION 

Check the flags parameter to make sure that the correct 
bits are set. Some calls may return information through 
the fl ags parameter and the bits returned may not be 
valid input on subsequent calls. 
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8 

MESSAGE 

NSR_0PT_0PTI0H 


CAUSE 

Illegal option. An illegal option was specified in the opt 
parameter. 


ACTION 

Check the opt parameter to make sure that it was 
correctly initialized with i ni topt () and that all options 
added with addopt () are defined for the system and 
system call. 

10 

MESSAGE 

NSRKINDANDPR0T0C0L 


CAUSE 

Protocol type mismatch. A protocol and a socket kind type 
were specified that are not supported together. 


ACTION 

One or more of the following actions may be taken: (1) 
Check the socket kind and protocol parameters for the 
correct values; (2) default the protocol value to zero, thus 
letting the system decide which protocols best support the 
referenced socket kind. 
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11 

MESSAGE 

NSRNOMEMORY 


CAUSE 

No memory. The system does not have enough memory 
available to support the request. This error can occur 
when you attempt to issue an i pccreate(), 
ipcconnect(), ipcrecvcn(), ipclookup(), or 
ipcdest() call. 


ACTION 

One or more of the following actions may be taken: (1) 
release some of the sockets or destination descriptors that 
are not currently being used; (2) if applicable, reduce the 
service requirements for the socket being created (eg., by 
requesting smaller message sizes); (3) determine if some of 
the other programs running on the system can release 
some of their networking resources. 

14 

MESSAGE 

NSRADDROPT 


CAUSE 

This error is returned to i pcdest () if an invalid value is 
specified in the proto 7 en parameter. The proto 1 en 
parameter indicates the length of a protocol address. 


ACTION 

Check the length specified in the protolen parameter. 

For TCP protocol addresses, the protocol parameter must 
be 2. 

15 

MESSAGE 

NSRNOFILEAVAIL 


CAUSE 

No file table entries are available. Close unnecessary open 
files and retry. 


ACTION 

If the error persists, reconfigure a larger File Table. 
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18 

MESSAGE 

CAUSE 

ACTION 

NSR_OPT_$YNTAX 

An error was detected in the option array syntax. 

Check the option array for valid fields. 

21 

MESSAGE 

NSR_DUP_0PTI0N 


CAUSE 

Duplicate option. At least one of the options in the opt 
parameter was specified twice. 


ACTION 

Check arguments input to addopt () when initializing the 
opt parameter. 

24 

MESSAGE 

NSR_MAX_CONNECTQ 


CAUSE 

Connection queued option error. An error was detected in 
the arguments regarding the maximum number of 
connections queued option in the opt parameter. 


ACTION 

Check the addopt () call that was used to put the 
NS0_MAX_C0NN_REQ option argument in the opt 
parameter. Must be less than or equal to 20. 

28 

MESSAGE 

NSRNLEN 


CAUSE 

Illegal name length. The name length was either too large 
or too small. 


ACTION 

Compare the name length to the acceptable range for this 
parameter. 
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29 

MESSAGE 

NSRDESC 


CAUSE 

Illegal descriptor. The referenced descriptor is outside of 
the acceptable range for socket descriptors. The descriptor 
might have been a disc file descriptor or a closed socket 
descriptor. 


ACTION 

Determine why the value was not within the acceptable 
range. One possible reason is that the call to allocate the 
descriptor failed. Also check for socket descriptors that 
had been already closed. 

30 

MESSAGE 

NSRCANTNAM E_VC 


CAUSE 

Cannot name VC socket. The calling process tried to 
name a VC socket using ipcname (). 


ACTION 

i pcname () cannot be invoked against VC sockets. 

31 

MESSAGE 

NSRDUPHAHE 


CAUSE 

Duplicate name. The name that i pcname() tried to assign 
to a socket was already in use. 


ACTION 

One of the following actions may be taken: (1) Pick 
another name; (2) wait and try again; (3) if several copies 
of the same process are running, make sure that each 
process has some way of generating a unique name, 
i pcname () has a random name generation facility that 
could be used, or the calling process could wait and try 
again later. 
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36 


MESSAGE NSRNAME TABLE_FULL 

CAUSE Name table full. A process attempted to bind a name to a 
socket via i pcname () when the system had no free name 
records. A name record must be allocated for each name 
that is bound to a socket. When the system runs out of 
name records, all succeeding i pcname () requests are 
rejected. 

ACTION Release some of the names that are bound to sockets. 

This may be done using i pcnamerase (). Because name 
records are system-wide resources shared by all NetIPC 
programs, the name records released by one program may 
be allocated for use by another. 

37 MESSAGE NSR_NAME_NOT_FOUND 

CAUSE Name not found. A process attempted to obtain a 

destination descriptor using i pci ookup(), but the name 
specified in the call was not registered in the referenced 
socket registry. 

ACTION One or more of the following actions may be taken: (1) 
Make sure that the name specified in the i pci ookup () 
call was the one that was intended; (2) consider that the 
failure could have been due to a race condition (the 
i pci ookup () caller could have executed its call before the 
i pcname () caller executed its call). 
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38 

MESSAGE 

NSR_N0_0WNER$HIP 


CAUSE 

No ownership. The caller invoked i pcnamerase () 
specifying a valid name but one bound to a socket that the 
it does not own. Only the owner of a call socket may 
purge its name. 


ACTION 

Check that the name specified is the one the caller 
intended to use. 

39 

MESSAGE 

NSR_NODE_NAME_SYNTAX 


CAUSE 

Illegal node name. The caller invoked i pci ookup (), 
ipedest(), or ipcsetnodename() passing it a node 
name having an illegal syntax (for example, too many levels 
of hierarchy or too many characters in one of the name 
parts). 


ACTION 

Verify that the name passed was the intended one or verify 
that the length specified for the passed name was correct. 

40 

MESSAGE 

NSRN0N0DE 


CAUSE 

Unknown node. The caller invoked i pci ookup () or 
i pedest () with the name of a node that was unknown to 
the local node. A local node resolves a node name by 
using the PROBE protocol. 


ACTION 

One or more of the following actions can be taken: (1) 
Verify that the name specified was the intended one; (2) 
check to see if the node is down; (3) verify that the 
node name command was executed to assign the node name 
or (4) if the node exists on a remote network, verify that a 
proxy server exists on the local network and that it has an 
entry configured for the remote node. If the remote node 
is non-HP-UX, check that IEEE 802.3 is turned on locally 
(use the lanconfig command). 
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43 

MESSAGE 

NSRCANTCONT ACTSERVER 


CAUSE 

Could not send an i pci ookup() request. Problem may be 
due to lack of kemal memory or the system may be heavily 
loaded. 


ACTION 

Try again. 

44 

MESSAGE 

NSRNOREGRES PONSE 


CAUSE 

No socket registry response. A name look up query was 
sent to the remote socket registry referenced in an 
i pci ookup () call, but the registry never responded. The 
node upon which the socket registry resides might be 
down, unreachable, or the system may be heavily loaded 
and not responding. 


ACTION 

If the node crashed, is temporarily unreachable or heavily 
loaded, the caller may wait and try again later. If the 
remote node is non-HP-UX, use lanconfig to verify that 
IEEE 802.3 is turned on locally. 

45 

MESSAGE 

NSRSIGNALINDICATION 


CAUSE 

System call aborted due to signal. 


ACTION 

Retry if appropriate. 
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46 

MESSAGE 

NSRPATHREPORT 


CAUSE 

Could not interpret path. The address information 
referenced by the specified destination descriptor 
contained uninterpretable information. When this error 
occurs, it may be indicative of a system software error. It 
may also indicate that the destination descriptor was 
somehow corrupted between the time it was generated and 
the time it was interpreted. 


ACTION 

Assuming the problem is due to corruption of the 
destination descriptor and not a system software error, try 
shutting down the referenced destination descriptor and 
then performing another i pci ookup (). If the same error 
is returned when the new destination descriptor is used, 
this error requires HP notification. 

47 

MESSAGE 

NSRBADREGMSG 


CAUSE 

Received corrupted message from socket registry. 


ACTION 

Retry. If the problem persists, this error requires HP 
notification. 

50 

MESSAGE 

NSRDLEN 


CAUSE 

Bad length. The data length specified was either too long 
or too short. 


ACTION 

One or more of the following actions may be taken: (1) 
Verify that the data length specified was the data length 
intended; (2) Verify that the size specified was not larger 
or smaller than maximum or minimum permissible receive 
size of the socket 
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51 

MESSAGE 

NSR_DEST 


CAUSE 

Not a destination descriptor. The descriptor specified in 
the parameter reserved for destination descriptors did not 
describe a destination descriptor. 


ACTION 

(1) Verify that the descriptor was the one intended; (2) 
Verify that you meant to execute an i pcdest () or 
ipclookup() call. 

52 

MESSAGE 

NSRPROT OCQLMISMATCH 


CAUSE 

Protocol mismatch. The call socket referenced in an 
i pccreate () or i pedest () call is not bound to any of 
the protocols that the destination descriptor references 
(i.e., there is no way to use the protocol referenced by the 
call socket to access the socket referenced by the 
destination descriptor). 


ACTION 

One of the following actions may be taken: (1) Do not 
specify a particular protocol when creating the call socket. 
Instead, use the default protocol value of zero in 
ipccreate()’s protocol parameter; (2) create a new call 
socket and bind it to a different protocol and try again. 

53 

MESSAGE 

NSRSOCKETMISMATCH 


CAUSE 

Socket type mismatch. The destination descriptor specified 
in an ipcconnect() call does not reference a remote call 
socket. This error occurs when the remote socket is 
supported by a system that supports socket kinds other 
than those supported on the local system. 


ACTION 

None, unless the remote application that the calling 
process wants to connect to can be modified to use call 
sockets. 
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54 

MESSAGE 

N$R_NOT_CALL_SOCKET 


CAUSE 

Not a call socket descriptor. 


ACTION 

(1) Verify it is the one intended; (2) Verify the original 
ipccreate() call. 

56 

MESSAGE 

NSRWOULDBLOCK 


CAUSE 

Would block error. The calling process issued a request 
that could not be immediately satisfied against a socket 
that was in asynchronous mode. 


ACTION 

This is an informational message so no action is necessary. 
For more information on asynchronous I/O, refer to the 
“NetIPC Concepts” chapter. 

59 

MESSAGE 

N$R_$0CKET_TIMEOUT 


CAUSE 

Timed out. The calling process’s request timed out. The 


request was an i pcsel ect () call or a NetIPC call issued 
against a socket that was in synchronous mode (the default 
mode for NetIPC sockets). Time out errors that occur on 
calls issued against VC sockets do not concern the protocol 
or connection they reference; protocols use their own 
timers to determine if a connection is not functioning 
reasonably. Possible scenarios in which this error could 
occur include: (1) An i pcsend () call could not obtain the 
buffer space needed to accommodate its data within the 
synchronous time-out interval; (2) an i pcrecv () call’s 
request for data could not be satisfied within the 
synchronous time-out interval; (3) a connection request 
was not received by an i pcrecvcn () call within the 
synchronous time-out interval; (4) a process attempted to 
send or receive data before a virtual circuit connection was 
established. 

ACTION Check your programs to make sure that the event the 
socket is expecting will indeed occur. In scenarios 1 
through 3 above, you should also consider modifying the 
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socket’s associated time out interval. Refer to the 
discussion of ipccontrol () in the “NetIPC Calls” 
chapter for information on adjusting the synchronous 
time-out. If scenario 4 has occurred, make sure your 
programs are synchronized as shown in the “NetIPC 
Concepts” chapter. 


60 

MESSAGE 

NSRNODESCAYAIL 


CAUSE 

The file descriptor limit was exceeded. The calling process 
attempted to gain access to a new socket descriptor or 
destination descriptor even though it already owned the 
maximum permissible number of descriptors (60). 


ACTION 

The process must release one of the socket descriptors or 
destination descriptors that it owns and then retry the 
request. 
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62 MESSAGE NSRCNCTPENDING 

CAUSE i pcrecv () expected. An attempt was made to manipulate 

a VC socket whose corresponding connection had been 
initiated with ipcconnect() but whose successful 
establishment had not been completed via i pcrecv (). A 
user cannot send or receive on a VC socket that was 
created with i pcconnect () without first having called 
i pcrecv () to complete the establishment sequence. 

ACTION Call i pcrecv () to verify that the connection referenced 
by the VC socket came up before trying to send or receive 
again. 

64 MESSAGE NSRREMOTEABORT 

CAUSE Connection aborted. The connection underlying a VC 
socket has been aborted either by the protocol handler 
running on the local node because it was unable to contact 
its peer protocol handler at the remote end of the 
connection, or by the protocol handler on the node at the 
other end of the connection. This error may be returned 
when (1) the remote node is down, (2) some network links 
are malfunctioning, (3) the network is extremely congested, 
(4) the user of the connection told the remote protocol 
handler to abort the connection, or (5) the remote process 
aborted. This error can be used to detect that the remote 
peer has completed transmission and has shut down the 
connection. 

ACTION Consult your Network Manager for assistance in 
diagnosing the problem. 
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65 


MESSAGE NSR LOCAL ABORT 


CAUSE Connection aborted. The connection underlying a VC 
socket has been aborted by the protocol handler running 
on the local node because it was unable to contact its peer 
protocol handler at the remote end of the connection. 

This error may be returned when (1) the remote node goes 
down, (2) some network links are malfunctioning, (3) the 
network is extremely congested, (4) or the connection 
could not be established because there is not a common 
encapsulation method. 

ACTION Consult your Network Manager for assistance in 

diagnosing the problem. Use the lanconfig command to 
verify that the local and remote nodes have a common 
encapsulation method (IEEE or Ethernet). 

66 MESSAGE NSR_N0T_C0NHECTI0N 

CAUSE Not a VC socket. The descriptor specified in the 

parameter reserved for VC socket descriptors did not 
describe a VC socket. 

ACTION One or more of the following actions may be taken: (1) 
Verify that the descriptor specified was the one that the 
calling process intended to specify; (2) verify that the 
original call to create the VC socket succeeded; (3) do not 
use Berkeley sockets with NetIPC calls. 
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74 

MESSAGE 

NSR_REQUEST 


CAUSE 

Illegal request. The request code passed in an 
i pccontrol () request was not valid. Or, the request is 
not valid for the kind of socket 


ACTION 

One or more of the following actions may be taken: (1) 
Verify that the request code specified was the intended 
one; (2) verify that the request code is supported on the 
local system (consult the “NetIPC Concepts” chapter); (3) 
Verify that the request is meaningful for the kind of socket. 

76 

MESSAGE 

NSRTIMEOUTVALUE 


CAUSE 

Illegal time out value. The i pccontrol () or 
i pcsel ect () request invoked by the calling process 
specified a time out value that was invalid. 


ACTION 

One or more of the following actions may be taken: (1) 
Verify that the time out value specified was the intended 
value; (2) consult the “NetIPC Concepts” chapter to make 
sure the value is acceptable. 

99 

MESSAGE 

NSR_VECT_COUNT 


CAUSE 

Bad vector data length. The calling process specified a 
data vector argument that contained a negative length field. 


ACTION 

Recheck the initialization of the data vector. 
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100 

MESSAGE 

NSRT 00MANYVECT S 


CAUSE 

Too many vectored data descriptors. 


ACTION 

Recode your program so that the number of vectored data 
descriptors is within acceptable limits. Refer to the 
“NetIPC Concepts” chapter for information on data 
vectors. 

106 

MESSAGE 

NSRDUPADDRESS 


CAUSE 

Address in use. The caller process requested that its call 
socket descriptor be bound to a particular protocol 
address, but the address was already bound to another call 
socket descriptor. 


ACTION 

One or more of the following actions may be taken: (1) 
Verify that the address specified was the intended one; or 
(2) check to make sure there are not duplicate copies of 
the program running. 

109 

MESSAGE 

NSRREMOTERELEASED 


CAUSE 

The remote endpoint of the connection has been released. 
You can continue to send on the local endpoint, but data 
will not be received. 


ACTION 

This is an informational message only. No action is 
required. 
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116 

MESSAGE 

NSRDESTUNREACHABLE 


CAUSE 

No usable paths. The local node’s protocol software 
cannot connect to the remote node described by the 
destination referenced by a passed destination descriptor. 
This could occur because the local node does not know 
where the remote node’s network is, or because the 
remote node does not support the same protocols as the 
local node. 


ACTION 

Obtain a new destination descriptor using i pci ookup (). 

If this is not successful, ask the System Manager to verify 
that the correct routing information is configured locally so 
that the remote network can be reached. Also, determine 
which protocols are supported by the remote node. 

118 

MESSAGE 

NSRVERSION 


CAUSE 

Version number mismatch. 


ACTION 

Make sure that all processes are running on nodes with the 
same version of the LAN software. 

124 

MESSAGE 

NSROPTENTRYNUH 


CAUSE 

Bad entry number specified. 


ACTION 

Check syntax of opt structure. 

125 

MESSAGE 

NSROPTDATALEN 


CAUSE 

Bad option data length. The data length specified in the 
addopt () or readopt () call was invalid. 


ACTION 

Verify that the value passed was the intended value. 
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126 

MESSAGE 

NSROPTTOTAL 


CAUSE 

Bad option total, initopt() was invoked specifying that 
the number of eventual entries to be placed into the opt 
parameter would be either fewer than zero or greater than 
the maximum possible number of opt entries. 


ACTION 

One or more of the following actions may be taken: (1) 
Verify that the value passed for the eventual number of 
entries argument was the intended value; (2) recalculate 
the number of entries that will actually be needed. 

127 

MESSAGE 

NSROPTCANTREAD 


CAUSE 

Cannot read option. The opt entry specified in the 
readopt () call was not initialized. 


ACTION 

One or more of the following actions may be taken: (1) 
Verify that the opt parameter was properly initialized with 
i n i topt (); (2) verify that the referenced entry was set up 
properly with addopt (). 
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1002 

MESSAGE 

NSRTHRESHVALUE 


CAUSE 

Bad threshold value. This error is returned for one of the 
following reasons: (1) an illegal read threshold was 
specified, or (2) an illegal write threshold was specified. 


ACTION 

Verify that the value passed was the intended value and 
that it was not negative or zero or greater than the socket's 
maximum receive size specified when the socket was 
created. 

2003 

MESSAGE 

NSRN0TALL0WED 


CAUSE 

User not a super user. The caller attempted to use 
functionality restricted to super users. 


ACTION 

This is an informational message only. No action is 
required. 

2004 

MESSAGE 

NSR_MSGSIZE 


CAUSE 

The message size being used is too large for the protocol. 
This error if a process requests a maximum send or receive 
size larger than the maximum allowed or if a process 
attempts to send or receive more than the number of bytes 
set in the i pcconnect () or i pcrecv () call. 


ACTION 

Make sure your i pcconnect () or i pcrecv () call does 
not attempt to set the maximum send and receive sizes to 
larger than 32,767 bytes. Also, make sure your process 
does not attempt to send or receive more bytes than 
specified by the i pcconnect () call or i pcrecv () call for 
that connection. 
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MESSAGE NSRADDRNOTAYAIL 

CAUSE Tries to connect to an unavailable protocol address. 

ACTION (1) Verify the destination descriptor was the one intended 
to use, or, (2) Verify the protocol address is correct and 
available for connection. 


Error Messages B-21 





System Calls and NetIPC Sockets 


NetIPC processes make use of sockets via the NetIPC calls to establish connections 
and exchange data. The Transport Layer’s Transmission Control Protocol (TCP) 
regulates the transmission of data to and from sockets. NetIPC processes reference 
sockets with socket descriptors. Socket descriptors are returned to processes when 
certain NetIPC calls are invoked. Socket descriptors are allocated from the same 
space as file descriptors. Therefore, sockets are accessible through the standard 
HP-UX file system calls. 

Table C-l describes HP-UX system calls that operate on NetIPC sockets. The 
NetIPC calls are described in the “NetIPC Calls” chapter. HP-UX system calls are 
described in the HP-UX Reference Manual. 
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Table C-1. System Calls and NetIPC Sockets 


HP-UX Call 

Description 

acct() 

The ac_i o field in accounting file records will be updated. 

close() 

When close() is used on a NetIPC socket, it does not 
guarantee that any data buffered will actually be sent. 

dup() 

Supported as described in the HP-UX Reference Manual. 

exec() 
execve() 

Sockets remain open over exec() and/or execve(). 

fchown() 

Not supported for NetIPC sockets. 

fork() 

Socket descriptors are inherited by the child process. 

Refer to the “NetIPC Concepts” chapter for more 
information on shared socket descriptors. 

fstat() 

The stat structure is undefined. 

read() 

Supported as described in the HP-UX Reference Manual 
for VC sockets only. 

select() 

Read and write thresholds for sockets are supported. 

Read, write and exception conditions for sockets are 
defined in the “NetIPC Calls” chapter. 

ulimit() 

No limits are currently supported for NetIPC usage. 

write() 

Supported for VC sockets only. 
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LAN/9000 Series 600/800 Migration 


This appendix provides an introduction to LAN/9000 Series 600/800 for users who are 
current DS/1000-IV, NS/1000 or NS/9000 Series 200 or 500 customers. Because it 
addresses three different audiences, this appendix is organized into three different 
sections: 

■ LAN/9000 Series 600/800 for DS/1000-IV Users. This section compares 
DS/1000-IV and LAN/9000 Series 600/800. 

■ NS/1000 to LAN/9000 Series 600/800 Migration. This section compares NS/1000 
and LAN/9000 Series 600/800. For information on porting NS/1000 applications to 
LAN/9000 Series 600/800, see the “Porting NetIPC Programs” appendix. 

■ NS/9000 to LAN/9000 Series 600/800 Migration. This section compares the 
NS/9000 product provided on the HP 9000 Series 200 and 500 to LAN/9000 Series 
600/800. 


Note For information on migrating from DS/1000-IV, NS/1000 or NS/9000 to 
NS/9000 Series 600/800, refer to the Using Network Services (NS)19000 
Series 6001800 manual. 
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LAN/9000 Series 600/800 for DS/1000-IV Users 

LAN/9000 Series 600/800 and DS/1000-IV do not share any common user services. 
As a result, programs written using DS/1000-IV calls are not transportable to 
LAN/9000 Series 600/800 systems. 


Migration Analysis Utility 

In order to help customers migrate from DS/1000-IV to LAN/9000 Series 600/800, 
Hewlett-Packard has developed a utility that reads RTE program source files and 
flags DS/1000-IV calls. This program can be used as an aid in determining the 
difficulty of converting a program to use LAN/9000 Series 600/800 calls and in 
locating calls that must be modified. 

For more information about this utility, refer to the PORT!HP-UX Migration Analysis 
Utility Manual (92561-90002). 


Feature Comparison 

Table D-l maps the DS/1000-IV services to LAN/9000 Series 600/800 and NS/9000 
Series 600/800 services with similar functionality. There is no one-to-one 
correspondence between DS/1000-IV and LAN/9000 Series 600/800 or NS/9000 Series 
600/800 services. 


Table D-1. DS/1000-IV vs. LAN & NS/9000 Series 800 



Similar LAN & NS/9000 

DS/1000-IV Service 

Series 800 Service 

Program-to-Program 

Network Interprocess 

Communication (PTOP) 

Communication (NetIPC) 

REMAT 

Network File Transfer (NFT) 

RMOTE 

Network File Transfer (NFT) 
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Note 


Network File Transfer are services provided by NS/9000 Series 600/800. 
Refer to the Using Network Services (NS)19000 Series 600(800 manual for a 
detailed comparison of DS/1000-IV and NS/9000 Series 600/800 product 
features. 


DS/1000-IV and LAN/9000 Series 600/800 share two similar services: PTOP and 
NetIPC. The following paragraphs compare these services. 


Interprocess Communication 

The DS/1000-IV service Program-to-Program Communication (PTOP) allows a 
master program to exchange information with and control the execution of a slave 
program. PTOP calls are divided into two categories, master calls and slave calls. The 
master and the slave programs may be located at the local node, or one may be at the 
local node and the other may be at a remote node. DS/1000-IV PTOP programs can 
communicate with other PTOP programs on remote DS/1000-IV or DS/3000 nodes. 

LAN/9000 Series 600/800 provides a service similar to PTOP called Network 
Interprocess Communication (NetIPC) which is documented in this manual. NetIPC 
allows two or more peer processes to exchange information; one program does not 
control the execution of another. Because NetIPC operates in a peer-to-peer rather 
than master-to-slave fashion, any NetIPC process can use any of the NetIPC calls. As 
a result, the form of interprocess communication offered by NetIPC is more flexible 
than that provided by PTOP. NetIPC peer processes may be located on the same or 
different nodes. 

NetIPC processes establish connections with other processes via sockets. A NetIPC 
process can engage in a dialogue that references certain sockets in order to create a 
connection with another NetIPC process. Several NetIPC calls are provided to allow 
processes to engage in this dialogue. Once a connection, called a virtual circuit, is 
established, the processes may exchange data. A LAN/9000 Series 600/800 NetIPC 
process can communicate with other NetIPC processes on remote LAN/9000 Series 
600/800 and NS/1000 nodes only. 

Unlike PTOP, NetIPC does not provide a call to schedule a remote process. Remote 
processes must be manually started or can be daemons that are started at system start 
up. 
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Table D-2 maps the DS/1000-IV PTOP calls to similar LAN/9000 Series 600/800 
NetIPC calls. Most of the NetIPC calls have no PTOP equivalents; therefore, they 
are not listed in the table. These calls are not similar to any PTOP calls because they 
are primarily used to create and establish virtual circuit connections. The NetIPC 
calls that have no PTOP equivalents include ipcconnect (), ipccreate(), 
ipcdest(), ipclookup(), ipcname(), ipcnamerase(), ipcrecvcn(), 
ipcselect(), addopt(), initoptQ, and readopt(). 


Table D-2. PTOP Calls vs. NetIPC Calls 


PTOP 

Call 

NetIPC 

Call 

Comparison 

P0PEN 

No similar 
NetIPC call. 

Series 600/800 NetIPC does not provide a 
call to schedule a peer process. 

PREAD 

ipcrecv() 

PREAD allows a PTOP master program to 
receive data contained in the buffer 
parameter of a slave program’s ACEPT call. 
The master program must call PREAD 
before the slave program can transmit data 
via an ACEPT call, i pcrecv () allows a 
NetIPC process to receive data queued on 
a virtual circuit connection. The data 
becomes queued on this connection when 
another NetIPC process calls i pc send (). 

PWRIT 

ipcsend() 

PWRIT allows a PTOP master program to 
transfer data contained in its buffer 
parameter to the buffer parameter of a 
slave program’s GET call. ipcsend() 
allows a NetIPC process to send data on a 
virtual circuit connection. The data 
becomes queued on this connection and 
may be dequeued by another NetIPC 
process when that process calls i pcrecv (). 
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Table D-2. PTOP Calls vs. NetIPC Calls-con’t 


PTOP 

Call 

NetIPC 

Call 

Comparison 

PCONT 

ipcsend() 

PCONT allows a PTOP master program to 
transfer data contained in its tag 
parameter to the tag parameter of a slave 
program’s GET call. 

PCLOS 

ipcshutdown() 

PCLOS allows a PTOP master program to 
terminate a slave program. If the slave 
program resides on an HP 1000 node, 

PCLOS also terminates logical 
communication with that node, 
i pcshutdown () may be used to abort a 
virtual circuit connection. This terminates 
logical communication with a peer process 
over that connection, i pcshutdown () can 
not be used to terminate a peer process; 
NetIPC does not provide a call with this 
functionality. 

PNRPY 

ipccontrol() 

PNRPY allows a PTOP master program to 
issue PWRIT, PCONT and PCLOS requests 
asynchronously. Master programs that use 
this call will not be suspended when they 
issue requests to send data to, or to 
terminate, slave programs. The NetIPC 
call ipccontrol () may be used to enable 
asynchronous I/O between NetIPC 
processes. Unlike PNRPY, i pccontrol () 
allows processes to both send and receive 
data asynchronously by placing the sockets 
shared by the processes in asynchronous 
mode. 
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Table D-2. PTOP Calls vs. NetIPC Calls-con’t 


PTOP 

NetIPC 


Call 

Call 

Comparison 

GET 

ipcrecv() 

The main function of the PTOP slave call 



GET is to receive master program requests 
(PWRIT, PREAD, etc.) However, the tag and 
buffer parameters of the GET call can be 
used to receive data sent by the master 
program. The NetIPC call i pcrecv () is 
similar to GET only in that it allows a 
process to receive data. (Refer to the 
discussion of PREAD above for more 



information on ipcrecv().) 

ACEPT 

ipcrecv() and 

The PTOP slave call ACEPT allows PTOP 


ipcsend() 

slave programs to receive data from, and 
send data back, to PTOP master programs. 
When a master program sends data via a 
call to PWRIT, the buffer parameter of the 
ACEPT call can be used to receive the data. 



When a master program requests data via a 
call to PREAD, the ACEPT’s buffer 
parameter contains the data that will be 
transmitted to the master program. The 
ACEPT call also contains a tag parameter 
that can be used to send data to the master 



program. The ACEPT call’s data 
acceptance and transmission functions are 
similar to ipcrecv() and ipcsend(), 
respectively. (Refer to the discussion of 
PWRIT and PREAD above for more 
information on these NetIPC calls.) 
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Table D-2. PTOP Calls vs. NetIPC Calls-con’t 


PTOP 

Call 

NetIPC 

Call 

Comparison 

REJCT 

ipcsend() 

The main function of the PTOP slave call 
REJCT is to reject a master request. REJCT 
also contains a tag field that can be used to 
transmit data back to the master program. 
This secondary feature of REJCT is similar 
to the NetIPC call i pcrecv (). (Refer to 
the discussion of PREAD above for more 
information on i pcrecv ().) 

FINIS 

ipcshutdown() 

The PTOP slave call FINIS is similar to 
the PTOP master call PC LOS in that it 
terminates communication between two 
programs. The NetIPC call 
ipcshutdown() terminates logical 
communication over a certain connection. 
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NS/1000 to LAN/9000 Series 600/800 Migration 

NS/1000 and LAN/9000 Series 600/800 share the same HP AdvanceNet NS user 
service NetlPC. NS/1000 and NS/9000 Series 600/800 also share the same HP 
AdvanceNet NS user service Network File Transfer (NFT). 

Refer to Appendix E, “Porting NetlPC Programs,” in this manual for information 
regarding transporting NS/1000 NetlPC programs to the LAN/9000 Series 600/800 
programming environment. Refer to the Using Network Services (NS)19000 Series 
600/800 manual for a detailed comparison of the NS/1000 and NS/9000 Series 600/800 
NFT implementations. 

As shown in the previous section, “LAN/9000 Series 600/800 for DS/1000-TV Users,” 
NS/lOOO’s DS/1000-IV Compatible Services (Remote File Access, Distributed 
Executive, Program-to-Program Communication, REMAT, RMOTE and Remote File 
Access) are not supported on LAN/9000 Series 600/800 nodes. 

In order to help customers migrate from DS/1000-IV to LAN/9000 Series 600/800, 
Hewlett-Packard has developed a utility that reads RTE program source files and 
flags DS/1000-TV calls. This program can be used as an aid in determining the 
difficulty of converting a program to use LAN/9000 Series 600/800 calls and in 
locating calls that must be modified. For more information about this utility, refer to 
the PORT/HP-UX Migration Analysis Utility Manual 

Table D-3 maps the NS/1000 services to the same or similar LAN/9000 Series 600/800 
and NS/9000 Series 600/800 services. 
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Table D-3. NS/1000 vs. LAN & NS/9000 Series 800 


NS/1000 Service 

LAN or NS/9000 Series 800 
Service 

Network File Transfer (NFT)* 

Network File Transfer (NFT)* 

Network Interprocess 
Communication (NetIPC)* 

Network Interprocess 

Communication (NetIPC)* 

Program-to-Program 
Communication (PTOP) 

Network Interprocess 

Communication (NetIPC) 

REMAT 

Network File Transfer (NFT) 

RMOTE 

Network File Transfer (NFT) 


*Indicates compatible HP AdvanceNet NS user services. 


Note Network File Transfer is a service provided by the NS/9000 Series 
600/800 product. Refer to the Using Network Services (NS)/9000 
Series 600/800 manual for a detailed comparison of the NS/1000 
and NS/9000 Series 600/800 user services. 
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NS/9000 to LAN/9000 Series 600/800 Migration 

LAN/9000 Series 600/800 and the NS/9000 product for the HP 9000 Series 200 and 
500 do not share any common services. NS/9000 Series 500 Interprocess 
Communication (“IPC”) and NS/9000 Series 600/800 Network Interprocess 
Communication (NetIPC) are not compatible services. 

NS/9000 Series 600/800 and NS/9000 Series 200 and 500, however, do share the 
Network File Transfer (NFT). Refer to the Using Network Services manual for a 
detailed comparison of the Series 600/800 and NS/9000 user services. 

Table D-4 maps the NS/9000 Series 200 and 500 services to the same or similar 
NS/9000 Series 600/800 and LAN/9000 Series 600/800 services. 


Table D-4. NS/9000 vs. NS & LAN/9000 Series 800 


NS/9000 Series 200 & 

500 Service 

NS & LAN/9000 

Series 800 Service 

Network File Transfer (NFT)* 

Interprocess Communication 
(IPC) (Series 500 only) 

Network File Transfer (NFT)* 

Network Interprocess 
Communication (NetIPC) 


indicates implementation of compatible user service. 

The following paragraphs provide a comparison of the NS/9000 Series 600/800 
NetIPC service and the NS/9000 Series 500 IPC service. 
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Interprocess Communication 

NS/9000 Series 500 Interprocess Communication (“IPC”) and LAN/9000 Series 
600/800 Network Interprocess Communication (NetIPC) are not compatible services. 
However, because the services are somewhat similar, it may be useful to convert an 
NS/9000 IPC program to use LAN/9000 Series 600/800 NetIPC calls. 

Features common to both NS/9000 Series 500 IPC and LAN/9000 Series 600/800 
NetIPC include the following: 

■ Processes communicate with each other by means of sockets. Before a connection 
can be established between two processes, each process must create a socket. On 
the Series 500, this socket is called a source socket; on the Series 600/800, it is 
called a call socket. 

■ Source (or call) sockets may be named. A process can gain access to another 
process’s socket by referencing the socket’s name. When the name of a socket that 
belongs to another process is referenced in a “look up” call (ui pci ookup () for the 
Series 500, i pci ookup () for the Series 600/800), the calling process receives a 

destination descriptor. 

■ Processes use destination descriptors in “connection request” calls 

(ui pcconnect () for the Series 500, i pcconnect ( ) for the Series 600/800). The 
connection request call returns a VC socket which is the endpoint of a virtual 
circuit connection. 

■ Communication between processes takes place over a virtual circuit connection. 

■ Connections can be set to synchronous or asynchronous communications mode. 

The default mode is synchronous, which is blocking mode. The communications 
mode can be reset to asynchronous using a “control” call (u i pccontrol () for the 
Series 500, i pccontrol () for the Series 600/800). 
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Porting NetIPC Programs 


This appendix summarizes differences and provides information to help you 
successfully port NetIPC programs between HP 1000 A-Series and HP 9000 Series 
600/800 systems. Refer to the NS/1000 User/Programmer Reference Manual for 
NetIPC programming information for HP 1000 A-Series systems. 

This appendix does not compare the programming language implementations at the 
different systems. For this information, you should refer to the following language 
reference manuals: 

SYSTEM LANGUAGE REFERENCE MANUALS 

HP 9000 HP FORTRAN 77/HP-UX Reference Manual 

Series 600/800 

HP C Reference Manual 

HP C/HP-UX Reference Manual Supplement 

HP Pascal Reference Manual 

HP 1000 FORTRAN 77 Reference Manual 

A-Series 

Pascal/1000 Reference Manual 

In addition, the following manuals contain information that is useful to programmers 
porting FORTRAN 77 and Pascal programs from the HP 1000 to the HP 9000 Series 
600/800: 

■ HP FORTRAN 77/HP-UX Migration Guide. 

■ HP Pascal/HP-UX Migration Guide. 
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When you are porting NetIPC programs, the following strategy may help: 

1. Make sure that the NetIPC programs are executing correctly between 
homogeneous systems. That is, the programs should work between HP 1000 
A-Series systems first. 

2. Port the programs using the language reference manuals. Check carefully for 
compiler differences such as data types and lengths. 

3. Check the differences between NetIPC calls documented in this appendix. Check 
all the parameters; some are not implemented or have different values. 

4. If your ported programs still do not work, consider both programming language 
and NetIPC differences. 
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LAN/9000 Series 600/800 and NS/1000 

This section describes the differences between the LAN/9000 Series 600/800 and 
NS/1000 NetIPC implementations. 


Path Report and Destination Descriptors 

In NS/1000 NetIPC, the descriptor returned by the socket registry software is called a 
path report descriptor, in LAN/9000 Series 600/800, this descriptor is called a 
destination descriptor. Although path report descriptors and destination descriptors 
have slightly different meanings, their function is the same: both contain addressing 
information that is used by a NetIPC process to direct requests to a certain call socket 
at a certain node. 


Socket Ownership 

An LAN/9000 Series 600/800 NetIPC process may own a maximum of 1024 
descriptors. This limit includes call socket, VC socket, and destination descriptors as 
well as HP-UX file descriptors and NetIPC and/or file descriptors inherited or 
otherwise opened by the process. 

An NS/1000 NetIPC process may own a maximum of 32 socket descriptors. This limit 
includes call socket, VC socket, and path report descriptors. 

NS/1000 and LAN/9000 Series 600/800 NetIPC process creates a call socket by calling 
IPCCreate; they create a VC socket by calling IPCConnect or IPCRecvCn. An 
NS/1000 NetIPC process may also gain access to a socket by calling I PCGi ve. Sockets 
are given away with the I PCGi ve call. 

The I PCGi ve and IPCGet calls are not part of the LAN/9000 Series 600/800 NetIPC 
implementation. Instead, LAN/9000 Series 600/800 processes can also acquire access 
to sockets owned by other NetIPC processes by utilizing socket “sharing.” On HP 
9000 Series 600/800 systems, NetIPC socket descriptors (call socket, VC socket, and 
destination), like HP-UX file descriptors, are copied to the “child” process when a 
process forks. As a result, more than one process can own a descriptor for the same 
socket. Programmers are responsible for regulating the use of shared sockets on 
LAN/9000 Series 600/800 systems. An NS/1000 NetIPC process creates a call socket 
by calling IPCCreate or IPCGet; it creates a VC socket by calling IPCConnect or 
IPCRecvCn. An NS/1000 NetIPC process may also gain access to a socket by calling 
I PCGi ve. Sockets are given away with the I PCGi ve call. 
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Socket Shut Down 

The I PCShutDown call is used in both NS/1000 and LAN/9000 Series 600/800 NetIPC 
to release a descriptor and any resources associated with it. The shut down procedure 
for both NS/1000 and LAN/9000 Series 600/800 processes is identical with the 
following exception: the operation of the LAN/9000 Series 600/800 implementation of 
I PCShutDown is affected by socket sharing. The LAN/9000 Series 600/800 supports 
NSFGRACEFULRELEASE. 

When a LAN/9000 Series 600/800 NetIPC process “shuts down” a VC socket 
descriptor that is shared by other processes, the descriptors owned by the other 
processes are not affected. The I PCShutDown call does not operate on the VC 
socket referred to by a VC socket descriptor unless the descriptor is the last 
descriptor for that socket. A VC socket is destroyed along with its VC socket 
descriptor only when the descriptor being released is the sole descriptor for that socket. 

When shutting down a shared call socket descriptor, the call socket referred to by the 
descriptor is destroyed along with the descriptor and names associated with the 
descriptor only if the descriptor being released is the last descriptor for that socket. If 
another process, or processes, have descriptors for the same socket, these duplicate 
descriptors, and any names associated with the descriptors, are not affected. 

When shutting down a shared destination descriptor, the addressing information 
stored in conjunction with the descriptor is destroyed along with the descriptor only if 
the descriptor being released is the sole descriptor for that information. If another 
process, or processes, have descriptors for the same information, these duplicate 
descriptors, and any names associated with the descriptors, are not affected. 


Signals 

Unlike NS/1000 NetIPC calls, LAN/9000 Series 600/800 NetIPC calls that would 
normally block may be interrupted by HP-UX signals. NetIPC calls that are 
interrupted by signals are optionally restartable. When a call is restarted after a 
signal, any time-outs (including the synchronous time-out) will be reset. As a result, 
signals that continuously interrupt/restart a NetIPC call at an interval shorter than the 
socket time-out will effectively void the time-out. Signals are explained in detail in 
the HP-UX Reference Manual. 
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TCP Checksum 


The NS/1000 IPCConnect and IPCRecvCn calls include a “checksumming” bit in 
their flags parameters. When set, this bit causes TCP to enable checksumming. 

Unlike NS/1000 NetIPC, the LAN/9000 Series 600/800 IPCConnect and IPCRecvCn 
calls do not include “checksumming” bits. When an NS/9000 Series 600/800 NetIPC 
process calls IPCConnect or IPCRecvCn, TCP checksumming is automatically enabled . 

TCP checksumming will always be performed if one or both NetIPC processes are 
LAN/9000 Series 600/800 processes. If both processes are NS/1000 NetIPC processes, 
TCP checksumming will be performed only if one or both processes call IPCConnect 
or IPCRecvCn with the “checksumming” bit set. 


Remote Process Scheduling 

NetIPC itself does not include a call to schedule a remote process. The method used 
to schedule a remote NetIPC process depends on the types of systems involved. For 
example, an NS/1000 NetIPC process written to schedule an NS/1000 peer process 
must be modified to utilize another scheduling method when it is ported to a 
LAN/9000 Series 600/800 system. 


Remote NS/1000 Process 

In order to schedule a remote NS/1000 NetIPC process from an NS/1000 node, you 
can use one of the following methods: the Remote Process Management (RPM) call 
RPMCreate, the Program-to-Program communication (PTOP) P0PEN call, one of the 
DEXEC scheduling calls, the REMAT QU command, or the TELNET virtual terminal 
service. 

You cannot use any of these services to schedule a remote NS/1000 process from a 
LAN/9000 Series 600/800 node because these services are only NS/1000 services. The 
“Process Scheduling” section in the “Cross-System NetIPC” chapter describes ways to 
schedule an NS/1000 NetIPC process from a LAN/9000 Series 600/800 node. 


Remote LAN/9000 Series 600/800 Process 

Remote LAN/9000 Series 600/800 processes can be manually started or can be 
scheduled by user-written daemons that are started at system start up. The “Process 
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Scheduling” section in “Cross-System NetIPC” chapter describes ways to schedule a 
LAN/9000 Series 600/800 NetIPC process from an NS/1000 node. 


Case Sensitivity 

Because the HP-UX operating system is case-sensitive, LAN/9000 Series 600/800 
NetIPC call names must be typed using lower case characters. For example, the 
NetIPC call IPCConnect must be typed as ipcconnect on LAN/9000 Series 600/800 
systems. 

NS/1000 NetIPC call names are not case sensitive and may be typed using lower case 
or upper case characters, or a combination of both upper and lower case characters. 


NetIPC Calls 

For the purposes of the following discussion, the NS/1000 and LAN/9000 Series 
600/800 NetLPC calls are divided into four categories: 

■ Calls that are unique to NS/1000 NetIPC. 

■ Calls that are unique to LAN/9000 NetIPC. 

■ Calls that are common to both NS/1000 and LAN/9000 Series 600/800 NetIPC and 
are implemented identically on each system. 

■ Calls that are common to both NS/1000 and LAN/9000 Series 600/800 NetIPC but 
are implemented differently on each system. 
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Unique NetIPC Calls 

The following calls are provided as part of the NS/1000 NetIPC implementation only: 

■ AdrOf . This call obtains the byte address of any byte within a data object. 

■ IPCGet. This call allows a process to obtain ownership of a call socket, path report 
or VC socket descriptor that was given away by another process with an I PCGi ve 
call. 

■ I PCGi ve. This call allows a process to “give up” a call socket, VC socket or path 
report descriptor so that another process may obtain it. 

The LAN/9000 Series 600/800 NetIPC implementation includes one call that is not 

provided by NS/1000 NetIPC: 

■ Opt Over Head. This call is used to determine the number of bytes needed for the 
opt parameter. 


Common NetIPC Calls 

The following NetIPC calls are common to both the NS/1000 and LAN/9000 Series 
600/800 NetIPC and are implemented identically. 


Table E-1. Identical NetIPC Calls 


AddOpt 

InitOpt 

IPCDest 

IPCLookUp 

IPCSend 

ReadOpt 


Call Comparison 

Table E-2 lists the differences between the NetIPC calls that are common to 
both the NS/1000 and LAN/9000 Series 600/800 NetIPC implementations but 
that are implemented differently. 
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Table E-2. NS/1000 and LAN/9000 Series 800 Call Comparison 


NetIPC Call Differences Between Implementation 

IPCConnect The NS/1000 implementation of IPCConnect defines a 
fl ags parameter bit that is not defined by the LAN/9000 
Series 600/800 implementation of the call: 
“checksumming” (bit 21). All LAN/9000 Series 600/800 
IPCConnect flags parameter bits must be clear (not 
set). NS/1000 NetIPC processes can enable TCP 
checksumming by setting the “checksumming” bit. If this 
bit is not set, TCP checksum will not be performed for 
the connection unless the process’s peer process calls 
IPCRecvCn with that call’s “checksumming” bit set, or the 
peer process is a LAN/9000 Series 600/800 NetIPC 
process. TCP checksumming is always enabled when the 
LAN/9000 Series 600/800 implementation of IPCConnect 
is called. 

Refer to “TCP Checksum” earlier in this appendix for 
more information. 

The LAN/9000 Series 600/800 implementation of 
I PCConnect allows a value of -1 to be assigned to the 
call’s calldesc parameter. This value causes a call socket 
to be created and then destroyed after the call completes 
successfully. The NS/1000 implementation of 
IPCConnect does not allow this value. 

The NS/1000 and LAN/9000 Series 600/800 
implementations of IPCConnect implement different 
maximum send and receive sizes. The NS/1000 maximum 
send and receive sizes are 8,000 bytes; the NS/9000 Series 
600/800 maximum send and receive sizes are 32,000 bytes. 
The default size on both implementations is 100 bytes. 
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Table E-2. NS/1000 and LAN/9000 Series 800 Call Comparison-con’t 


NetIPC Call differences Between Implementation 

IPCControl IPCControl includes four request codes that are not 
provided by the NS/1000 implementation of the call: 4, 
1002, 1003 and 9008. When request code 9008 is 
specified, the LAN/9000 Series 600/800 implementation 
of IPCControl allows a value of -1 in the call’s 
descriptor parameter; this is also not part of the 
NS/1000 implementation of the call. Refer to the 
“NetIPC Calls” chapter in this manual for a description 
of these request codes. 

Unlike the NS/1000 implementation of IPCControl, the 
operation of the LAN/9000 Series 600/800 IPCControl 
call is affected by socket sharing. Refer to “Socket 
Ownership” earlier in this appendix for more information 
about socket sharing. Refer to the “NetIPC Calls” 
chapter in this manual for a complete description of how 
socket sharing affects the IPCControl call. 

I PCCreate The NS/1000 and LAN/9000 Series 600/800 

implementations of I PCCreate support different ranges 
of permitted TCP protocol addresses that can be specified 
in the opt parameter. However, both implementations 
recommend that users specify TCP addresses in the range 
30767 to 32767 decimal. 

The NS/1000 and LAN/9000 Series 600/800 
implementations of I PCCreate also support different 
maximum connection request backlog defaults and ranges. 
The NS/1000 implementation has a default of three 
connection requests and an allowable range of zero to 
five; the LAN/9000 Series 600/800 implementation has a 
connection request default of one and an allowable range 
of 1 to 20. 

I PC Name The LAN/9000 Series 600/800 implementation of 

I PC Name allows for the naming of destination (also 
known as path) descriptors. The NS/1000 implementation 
of the call does not. 
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Table E-2. NS/1000 and LAN/9000 Series 800 Call Comparison-con’t 


NetIPC Call 

Diifferences Between Implementation 

IPCNamErase 

Unlike the NS/1000 implementation of IPCNamErase, the 
operation of the LAN/9000 Series 600/800 
implementation of IPCNamErase is affected by socket 
sharing. Refer to “Socket Ownership” earlier in this 
appendix for more information about socket sharing. 


Unlike the LAN/9000 Series 600/800 implementation of 
IPCNamErase, the operation of the NS/1000 
implementation of the call does not allow for erasing 
names assigned to path report (also known as destination) 
descriptors. 

IPCRecv 

The LAN/9000 Series 600/800 implementation of 

I PCRecv defines bit 26 of the call’s f 7 ags parameter as 
“more data.” This bit is not implemented on NS/1000. 
When this bit is set on a LAN/9000 Series 600/800, it 
indicates that non-delimited data was received. 

IPCRecvCn 

The NS/1000 implementation of IPCRecv includes a 
flags parameter bit that is not defined by the LAN/9000 
Series 600/800 implementation of the call: 

“checksumming” (bit 21). All LAN/9000 Series 600/800 
IPCRecvCn flags parameter bits must be clear (not set). 
NS/1000 NetIPC processes can enable TCP 
checksumming by setting the “checksumming” bit. If this 
bit is not set, TCP checksum will not be performed for 
the connection unless the process’s peer process called 
IPCConnect with that call’s “checksumming” bit set, or 
the peer process is a LAN/9000 Series 600/800 NetIPC 
process. TCP checksumming is always enabled when the 
LAN/9000 Series 600/800 implementation of IPCRecvCn 
is called. 


Refer to “TCP Checksum” earlier in this appendix for 
more information. 
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Table E-2. NS/1000 and LAN/9000 Series 800 Call Comparison-con’t 


NetiPC Call 

Diifferences Between Implementation 

IPCSelect 

The LAN/9000 Series 600/800 implementation of 

IPCSel ect allows the sdbound parameter to have a 
maximum value of 60. The NS/1000 implementation has 
an upper limit of 32. 

IPCShutDown 

Unlike the NS/1000 of IPCShutDown, the operation of 
the LAN/9000 Series 600/800 implementation of 
IPCShutDown is affected by socket sharing. Refer to 
“Socket Ownership” earlier in this appendix for more 
information. The HP 9000 supports 
NSF_GRACEFUL_RELEASE. 
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3-41 

protocol parameter 
ipccreate(), 3-36 
ipcdestQ, 3-39 
ipclookup(), 3-48 
problem resolution, B-2-B-3, B-ll 
Protocol types, 3-3 
protolen parameter, 3-40-3-41 
PWRIT, D-4-D-5 

R 

Read and write thresholds, 1-20 
Read select, 3-70 
Read threshold, 1-20-1-21,3-69 
read(), 1-6, C-2 
Readable VC socket, 1-20 
readdata parameter, 3-31-3-34 
readmap parameter, 3-67, 
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sdbound parameter, 3-67, 3-74, 
E-ll 

selectQ, 1-6, C-2 
Send size, 3-30, 3-66 
Sending and receiving data, 1-3, 
1-17 

setnodename(), 3-46 
SHORT INTEGER, 3-11 
Shutting down a connection, 1-3, 
1-23 

SIGRETURN, 1-22 
Signals, 1-22, E-4 
size parameter, 3-46 
Slave calls, D-3 
sleepQ, 3-49 
Socket, 1-3—1-4 
descriptor, 3-37 
maximum number, 2-5 
multiple descriptors, 3-34 
ownership, 1-7, E-3 
registry, 3-81 
sharing, E-3, E-10 
shutdown, 2-10, 2-13, 3-82, E-4 


Index-9 




status information, 1-20 
types, 3-3 

socketkind parameter, 3-50, 
B-3 

ipccreate(), 3-36 
ipcdest(), 3-39 
ipclookup(), 3-48 
problem resolution, B-2 
socketname parameter, 3-5, 
3-16 

ipclookupQ, 3-47 
ipcnameQ, 3-51 
ipcnamerase(), 3-54 
Software revision codes, 
2-2-2-3 

Source socket, D-ll 
stat(), 1-6 
Stream mode, 1-17 
Summary of NetIPC calls, 

1-3 

Synchronous 

I/O, 3-61, 3-64, 3-77 
mode, 1-18-1-19 
time-out, 1-20 
timer, 3-58 

vs. Asynchronous I/O, 3-77 
Syntax conventions, 3-1, 3-17 
System calls, C-l 

T 

tag parameter, D-5 
TCP, 3-57, C-l 

checksum, 3-29, 3-65, E-5, 
E-8, E-10 

NSFMOREDATA, 

3-75-3-76 

protocol address, 2-12, 
3-37-3-38 

TELNET Virtual terminal 
service, E-5 

timeout parameter, 3-68, 


3-70, 3-74 
Timer, 1-19 
Timing problems, 3-48 
Transmission buffer, 1-19 
Transmission control protocol, 

1-4, 3-36, 3-39 

u 

uipclookupQ, D-ll 
ulimitQ, C-2 

Unique NetIPC calls, E-7 
AdrOf, E-7 
IPCGet, E-7 
IPCGive, E-7 
OptOverHead, E-7 
Upper ordinal bound, 3-67 
Urgent data option, 2-13 
User-written daemons, 1-8 
Using flags in a C program, 3-6 

V 

VC connection 

interprocess communication, D-4 
ipcrecv(), 3-56, 3-59 
ipcrecvcn(), 3-63-3-64 
VC socket, 3-70, E-3 
exceptional, 3-69 

interprocess communication, D-ll 
ipcname(), 3-52 
ipcrecvcn(), 3-59, 3-63 
ipcselect(), 3-70 
ipcsend(), 3-77 

NSCRECVTHRESHRESET, 

3-32 

NSR_WOULD_BLOCK, 3-59 
readable, 3-69 
writeable, 3-69 
VC socket descriptor, 1-7 
ipcrecvcn(), 3-64 
ipcselectQ, 3-71 
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ipcshutdown(), 3-81 
vcdesc parameter, 1-7 
ipcconnectQ, 3-27-3-28 
ipcrecv(), 3-56 
ipcrecvcn(), 3-63 
ipcselect(), 3-71-3-72 
ipcsend(), 3-73, 3-75 
Vectored reading, 3-59 
Virtual circuit connection, 
D-ll 

w 

wlen, 3-31, 3-34 
Writable VC socket, 1-20 
Write select, 3-70 
Write threshold, 1-21, 3-32, 
3-69 

writeQ, 1-6, C-2 
writemap parameter, 3-68, 
3-70-3-74 
wrtdata parameter, 
3-31-3-32,3-34-3-35 
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